docs: optmize nav

docs/development/mkdocs.md

@@ -46,7 +46,29 @@ To create new documentation, do the following:
 
 - Create `doc_name.md` and `doc_name.zh.md` in the `/docs` folder. You can put them under a subfolder if necessary. Refer to the current directory structure and use your best judgment to decide the best place for that new doc.
 - Write the content of the doc. You can choose to write only the English doc or the Chinese doc; you don't have to (but it's highly recommended if you can) write documentation in both languages.
-- Update the `/mkdocs.yml` file, update the `nav:` section. It's the table of content of the whole doc website.
+- In most cases, you don't need to think about the navigation menu which is the table of content of the whole doc website. But If you need to customize the navigation menu, you can refer to [Setting up Navigation](#setting-up-navigation).
+
+## Setting up Navigation
+
+If you want to customize the navigation menu, you can update `nav:` section in `mkdocs.yaml`. We support wildcards and [subdirectory cross-link](https://oprypin.github.io/mkdocs-literate-nav/reference.html#subdirectory-cross-link). For example:
+
+```yaml
+nav:
+  - DTM Commands Explained in Depth:
+    - commands/autocomplete*.md
+    - commands/*.md
+  - Plugins:
+    - plugins/plugins-list*.md
+    - plugins/*.md
+  - Best Practices: best-practices/
+  - 'contributing_guide*.md'
+  - 'contributor_ladder*.md'
+```
+
+- Normally, 'contributing_guide*.md' will be expanded to 'contributing_guide.md' and 'contributing_guide.zh.md'
+- If you create documentation in the `commands/`, `plugins/`, and `best-practices/` directories, you will not need to update the `nav`.
+
+If you want to know more about the configuration of navigation, please refer to [Configure Pages and Navigation](https://www.mkdocs.org/user-guide/writing-your-docs/#configure-pages-and-navigation) and [Literate Nav Syntax](https://oprypin.github.io/mkdocs-literate-nav/)
 
 ## Review Your Change Locally
 

docs/requirements.txt

@@ -1,3 +1,4 @@
 mkdocs
 mkdocs-material
 mkdocs-i18n
+mkdocs-literate-nav

mkdocs.yml

@@ -75,113 +75,35 @@ plugins:
           Road Map: "路线图"
           Code Review Guide: "代码 review 指导"
           Overview: "概览"
+  - literate-nav
 nav:
   - Overview: 'https://docs.devstream.io'
-  - 'understanding_the_basics.md'
-  - 'understanding_the_basics.zh.md'
-  - 'core_concepts.md'
-  - 'core_concepts.zh.md'
-  - 'quickstart.md'
-  - 'quickstart.zh.md'
+  - 'understanding_the_basics*.md'
+  - 'core_concepts*.md'
+  - 'quickstart*.md'
   - DTM Commands Explained in Depth:
-    - 'commands/autocomplete.md'
-    - 'commands/autocomplete.zh.md'
-    - 'commands/init.md'
-    - 'commands/init.zh.md'
-    - 'commands/apply.md'
-    - 'commands/apply.zh.md'
-    - 'commands/verify.md'
-    - 'commands/verify.zh.md'
-    - 'commands/delete.md'
-    - 'commands/delete.zh.md'
-    - 'commands/destroy.md'
-    - 'commands/destroy.zh.md'
+    - commands/autocomplete*.md
+    - commands/*.md
   - Plugins:
-    - 'plugins/plugins-list.md'
-    - 'plugins/plugins-list.zh.md'
-    - 'plugins/argocd.md'
-    - 'plugins/argocd.zh.md'
-    - 'plugins/argocdapp.md'
-    - 'plugins/argocdapp.zh.md'
-    - 'plugins/devlake.md'
-    - 'plugins/devlake.zh.md'
-    - 'plugins/github-repo-scaffolding-golang.md'
-    - 'plugins/github-repo-scaffolding-golang.zh.md'
-    - 'plugins/githubactions-golang.md'
-    - 'plugins/githubactions-golang.zh.md'
-    - 'plugins/githubactions-nodejs.md'
-    - 'plugins/githubactions-nodejs.zh.md'
-    - 'plugins/githubactions-python.md'
-    - 'plugins/githubactions-python.zh.md'
-    - 'plugins/gitlab-repo-scaffolding-golang.md'
-    - 'plugins/gitlab-repo-scaffolding-golang.zh.md'
-    - 'plugins/gitlabci-generic.md'
-    - 'plugins/gitlabci-generic.zh.md'
-    - 'plugins/gitlabci-golang.md'
-    - 'plugins/gitlabci-golang.zh.md'
-    - 'plugins/hashicorp-vault.md'
-    - 'plugins/hashicorp-vault.zh.md'
-    - 'plugins/jenkins.md'
-    - 'plugins/jenkins.zh.md'
-    - 'plugins/jira-github-integ.md'
-    - 'plugins/jira-github-integ.zh.md'
-    - 'plugins/kube-prometheus.md'
-    - 'plugins/kube-prometheus.zh.md'
-    - 'plugins/openldap.md'
-    - 'plugins/openldap.zh.md'
-    - 'plugins/tekton.md'
-    - 'plugins/trello.md'
-    - 'plugins/trello.zh.md'
-    - 'plugins/trello-github-integ.md'
-    - 'plugins/trello-github-integ.zh.md'
-  - Best Practices:
-    - 'best-practices/gitops.md'
-    - 'best-practices/gitops.zh.md'
-  - 'contributing_guide.md'
-  - 'contributing_guide.zh.md'
-  - 'contributor_ladder.md'
-  - 'contributor_ladder.zh.md'
+    - plugins/plugins-list*.md
+    - plugins/*.md
+  - Best Practices: best-practices/
+  - 'contributing_guide*.md'
+  - 'contributor_ladder*.md'
   - Developer Guide:
-    - 'development/good-first-issues.md'
-    - 'development/good-first-issues.zh.md'
-    - Core Concepts in Detail:
-      - 'core-concepts/config.md'
-      - 'core-concepts/config.zh.md'
-      - 'core-concepts/core-concepts.md'
-      - 'core-concepts/core-concepts.zh.md'
-      - 'core-concepts/stateconfig.md'
-      - 'core-concepts/stateconfig.zh.md'
-      - 'core-concepts/variables.md'
-      - 'core-concepts/variables.zh.md'
-      - 'core-concepts/dependencies.md'
-      - 'core-concepts/dependencies.zh.md'
-      - 'core-concepts/output.md'
-      - 'core-concepts/output.zh.md'
-    - 'development/development-workflow.md'
-    - 'development/development-workflow.zh.md'
-    - 'development/project-layout.md'
-    - 'development/project-layout.zh.md'
-    - 'development/architecture.md'
-    - 'development/architecture.zh.md'
-    - Commands:
-      - 'development/commands/develop.md'
-      - 'development/commands/develop.zh.md'
-    - 'development/build.md'
-    - 'development/build.zh.md'
-    - 'development/test.md'
-    - 'development/test.zh.md'
-    - 'development/commit-messages.md'
-    - 'development/commit-messages.zh.md'
-    - 'development/lint.md'
-    - 'development/lint.zh.md'
-    - 'development/mkdocs.md'
-    - 'development/mkdocs.zh.md'
-    - 'development/reviewing.md'
-    - 'development/reviewing.zh.md'
-    - 'development/creating-a-plugin.md'
-    - 'development/creating-a-plugin.zh.md'
-    - 'development/branch-and-release.md'
-    - 'development/branch-and-release.zh.md'
+    - development/good-first-issues*.md
+    - Core Concepts in Detail: core-concepts/
+    - 'development/development-workflow*.md'
+    - 'development/project-layout*.md'
+    - 'development/architecture*.md'
+    - Commands: development/commands/
+    - 'development/build*.md'
+    - 'development/test*.md'
+    - 'development/commit-messages*.md'
+    - 'development/lint*.md'
+    - 'development/mkdocs*.md'
+    - 'development/reviewing*.md'
+    - 'development/creating-a-plugin*.md'
+    - 'development/branch-and-release*.md'
   - Road Map ⧉: 'https://github.com/devstream-io/devstream/blob/main/ROADMAP.md'
-  - 'troubleshooting.md'
-  - 'troubleshooting.zh.md'
+  - 'troubleshooting*.md'