fix(content-docs): use category index convention to infer document title

[MarkShawn2020]

Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

Motivation

I found if I have file path like xx/yy/zz/index.md or xx/yy/zz/readme.md without a 'tittle' frontmatter or '#1' title in the document, then the title of this file shown in the sidebar would be index or readme, which is not desired, since the directory name zz may be more suitable.

Test Plan

Test links

Deploy preview: https://deploy-preview-_____--docusaurus-2.netlify.app/

Related issues/PRs

[netlify]

✅ [V2]

Built without sensitive environment variables

Name	Link
🔨 Latest commit	353a125
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/63173a4a2937a20008490501
😎 Deploy Preview	https://deploy-preview-8052--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 73	🟢 98	🟢 100	🟢 100	🟠 80	Report
/docs/installation	🟠 75	🟢 100	🟢 100	🟢 100	🟢 90	Report

[slorber]

Thanks, that looks like a useful change that I'll classify as a bug fix (and not a breaking change)

Note we already have a convention to detect "category index documents", see

// By convention, Docusaurus considers some docs are "indexes":
// - index.md
// - readme.md
// - <folder>/<folder>.md
//
// This function is the default implementation of this convention
//
// Those index docs produce a different behavior
// - Slugs do not end with a weird "/index" suffix
// - Auto-generated sidebar categories link to them as intro
export const isCategoryIndex: CategoryIndexMatcher = ({
  fileName,
  directories,
}): boolean => {
  const eligibleDocIndexNames = [
    'index',
    'readme',
    directories[0]?.toLowerCase(),
  ];
  return eligibleDocIndexNames.includes(fileName.toLowerCase());
};

It makes sense to find a way to reuse the same logic instead of duplicating it.

We also want to cover such subtle behaviors with unit tests

Also note that with autogeneated sidebars, folders might have a number prefix for ordering reasons, and you may want to strip that number in the infered title: /xx/yy/03-zz/index.md should infer to zz and not 03-zz? (see impl of getSlug() for inspiration)

[MarkShawn2020]

Note we already have a convention to detect "category index documents", see

Good job！

We also want to cover such subtle behaviors with unit tests

Sorry to admit that I have few ideas on how to write unit tests for directory strucurues.

Also note that with autogeneated sidebars, folders might have a number prefix for ordering reasons, and you may want to strip that number in the infered title: /xx/yy/03-zz/index.md should infer to zz and not 03-zz? (see impl of getSlug() for inspiration)

Yep!