Skip to content

mcts-cpu-validate Markdown tree and symlink plan

1. Purpose

This file lists the Markdown files involved in the docs-site build.

It answers two questions:

  1. Which Markdown files are authored directly.
  2. Which Markdown files are reused through symlinks instead of being rewritten.

That split matters because this project treats DRY as a hard requirement. If a Markdown file is already the authoritative source, the docs site should not create a duplicate copy.

2. Conventions

2.1 Naming

  • Chinese files use .zh.md
  • English files do not use an en suffix

2.2 Status labels

  • direct-write: a file written or maintained directly
  • symlink: a file that reuses another Markdown source through a symbolic link

3. Docs-site specification files already in place

3.1 direct-write

  • docs-site/specs/mkdocs_prd.zh.md
  • docs-site/specs/mkdocs_prd.md
  • docs-site/specs/github_action_prd.zh.md
  • docs-site/specs/github_action_prd.md
  • docs-site/specs/md_tree.zh.md
  • docs-site/specs/md_tree.md

These files describe the documentation project itself, not the training system spec.

4. Root README plan

4.1 direct-write

  • README.zh.md
  • source path: renamed from the current root README.md with mv

  • role: Chinese primary README

  • README.md

  • role: new English primary README for the default GitHub repository view

5. Explanatory pages to author under docs-site/docs

5.1 Chinese direct-write files

  • docs-site/docs/zh/index.zh.md
  • docs-site/docs/zh/project-overview.zh.md
  • docs-site/docs/zh/training-loop.zh.md
  • docs-site/docs/zh/data-and-recovery.zh.md
  • docs-site/docs/zh/developer-notes.zh.md
  • docs-site/docs/zh/docs-specs.zh.md

5.2 English direct-write files

  • docs-site/docs/en/index.md
  • docs-site/docs/en/project-overview.md
  • docs-site/docs/en/training-loop.md
  • docs-site/docs/en/data-and-recovery.md
  • docs-site/docs/en/developer-notes.md
  • docs-site/docs/en/docs-specs.md
  • docs-site/docs/en/configuration.md
  • docs-site/docs/en/step-by-step-guide.md
  • docs-site/docs/en/data-readme.md

These files are already authoritative sources and should be reused through symlinks.

  • source: README.zh.md
  • target: docs-site/docs/zh/readme.zh.md
  • source: CONFIGURATION.md
  • target: docs-site/docs/zh/configuration.zh.md
  • source: STEP_BY_STEP_GUIDE.md
  • target: docs-site/docs/zh/step-by-step-guide.zh.md
  • source: data/README.md
  • target: docs-site/docs/zh/data-readme.zh.md
  • source: docs-site/specs/mkdocs_prd.zh.md
  • target: docs-site/docs/zh/specs/mkdocs-prd.zh.md
  • source: docs-site/specs/github_action_prd.zh.md
  • target: docs-site/docs/zh/specs/github-action-prd.zh.md
  • source: docs-site/specs/md_tree.zh.md
  • target: docs-site/docs/zh/specs/md-tree.zh.md
  • source: README.md
  • target: docs-site/docs/en/readme.md
  • source: docs-site/specs/mkdocs_prd.md
  • target: docs-site/docs/en/specs/mkdocs-prd.md
  • source: docs-site/specs/github_action_prd.md
  • target: docs-site/docs/en/specs/github-action-prd.md
  • source: docs-site/specs/md_tree.md
  • target: docs-site/docs/en/specs/md-tree.md

7. Why the English side uses entry pages plus Chinese authority sources

Some authoritative repository documents currently exist only in Chinese. The docs site still needs complete navigation and a DRY structure.

The rule is:

  1. English entry pages must exist.
  2. If the authority source only exists in Chinese, the English side first provides a direct-write entry page that explains the role of that document.
  3. If a full English authority source is added later, the entry page can be replaced by that source or a symlink to it without changing the docs-site structure.

So the English side keeps bilingual entry points without duplicating the Chinese authority files.

8. Markdown files excluded from this round

  • specs/*.md

Those files remain read-only in this task.

9. Suggested execution order

  1. Rename README.md to README.zh.md and add a new English README.md
  2. Author the explanatory docs-site pages
  3. Create all symlinks
  4. Configure MkDocs navigation for every page
  5. Add the GitHub Pages deployment workflow

10. Validation

The Markdown tree is in good shape when:

  1. direct-write files and symlinked files have clear boundaries
  2. every documentation topic has a visible entry in both language navigations
  3. each symlink clearly shows its source and target