Skip to main content

Docs Intro Page Maintenance Workflow

This document covers how to maintain the current knowledge base homepage, i.e. the entry page at /docs/intro.

This entry page is no longer a long Markdown document. It is now a thin MDX file that mounts a React component:

docs/intro.mdx
src/components/DocsIntro/
src/data/siteStats.generated.json
scripts/generate-site-stats.mjs

The purpose is to upgrade the "docs entry page" from a plain text page to a clearer site map: the first screen explains the knowledge base's scope, the section below shows main entry points by topic, and the top displays article count and cumulative word count.

File Responsibilities​

docs/intro.mdx​

This file only holds the Docusaurus-required front matter and imports the DocsIntro component.

Do not keep large blocks of prose here. Homepage content, link grouping, stats display, and visual structure should all live in the component. Otherwise you will end up with a messy state where the same entry page is controlled by both MDX body text and a React component.

src/components/DocsIntro/index.js​

This file maintains the content structure of the docs homepage.

It mainly contains:

  • TOPIC_GROUPS: topic groups, entry links, description text, and icon types shown on the homepage
  • CONTACT_LINKS: contact links at the bottom of the homepage
  • HERO_STATS: first-screen stats, currently combined from topic counts and generated statistics
  • Icon: a lightweight icon set used within the component

When adding a new major content section in the future, if it is a stable entry point and should appear on the docs homepage, update TOPIC_GROUPS at the same time.

If you are just adding a regular article, no changes here are needed. Article count and word count are automatically refreshed by the stats script.

src/components/DocsIntro/styles.module.css​

This file only handles the docs homepage component styles.

Things to watch when maintaining:

  • Homepage card links must be readable on both desktop and mobile
  • Stats numbers must not cause horizontal overflow as word counts grow
  • Dark theme must be checked alongside light theme
  • Colors, spacing, border-radius, and card styles should stay consistent with the existing site design

scripts/generate-site-stats.mjs​

This script scans Markdown/MDX files under docs/ and blog/, skips articles with draft: true, and generates:

{
  "docsArticleCount": 0,
  "blogPostCount": 0,
  "articleCount": 0,
  "wordCount": 0
}

Stats are written to:

src/data/siteStats.generated.json

wordCount is a rough readable word count for site display, not academic-grade precision. The script strips front matter, code blocks, inline code, MDX tags, image syntax, and plain link syntax, then counts Chinese characters and English alphanumeric words.

Build Process Changes​

The current package.json has wired stats refresh into both local dev and production builds:

npm start
npm run build

Both commands first run:

npm run generate:site-stats

So during normal development and pre-deployment builds, you do not need to manually refresh stats.

Only run this separately in these situations:

npm run generate:site-stats
  • You want to update src/data/siteStats.generated.json without starting Docusaurus
  • After bulk adding or deleting articles, you want to check stats first
  • After adjusting the stats script, you want to verify output independently

How To Add or Adjust Homepage Entries​

1. Confirm the Entry Is Stable​

Do not put temporary articles, unsystematic drafts, or content whose paths may still change into homepage entries.

The homepage is good for:

  • Long-term maintained topic sections
  • Content collections with stable category pages
  • The main threads a reader should see first when entering the knowledge base

2. Update TOPIC_GROUPS​

In src/components/DocsIntro/index.js, add or adjust entries in the corresponding group.

For each entry, confirm at minimum:

  • title is the display name
  • href is a stable, accessible path
  • meta is a short topic tag
  • description explains what this entry is good for reading
  • icon exists in the Icon function
  • accent coordinates with the current page color scheme

If you add a new icon type, also add the SVG path in Icon.

3. Do Not Let the Homepage Replace Directory Rules​

The homepage is a friendlier entry point. It does not replace Docusaurus's category pages, sidebars, or topic directory rules.

When adding a new topic directory, still follow:

In other words, first ensure the directory, _category_.json, sidebars.js, and routing are stable, then consider whether to feature it on the homepage.

Verification Checklist​

After modifying the docs homepage or stats script, run at minimum:

npm run build

Then check:

  1. src/data/siteStats.generated.json has been refreshed
  2. /docs/intro builds successfully
  3. Homepage topic card links have no broken links
  4. First-screen text and cards are readable in dark theme
  5. Stats area and card area have no horizontal overflow on mobile

If you only changed text and entry links, you usually do not need extra tests. If you modified the stats script logic, at least run npm run generate:site-stats separately to confirm the output format has not changed.