@docusaurus/plugin-content-docs 2.0.0-beta.1decd6f80 → 2.0.0-beta.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (230) hide show
  1. package/lib/categoryGeneratedIndex.d.ts +12 -0
  2. package/lib/categoryGeneratedIndex.js +37 -0
  3. package/lib/cli.d.ts +3 -2
  4. package/lib/cli.js +65 -69
  5. package/lib/client/docsClientUtils.d.ts +9 -28
  6. package/lib/client/docsClientUtils.js +34 -42
  7. package/lib/client/index.d.ts +22 -0
  8. package/lib/client/index.js +72 -0
  9. package/lib/constants.d.ts +4 -0
  10. package/lib/constants.js +4 -1
  11. package/lib/docs.d.ts +33 -4
  12. package/lib/docs.js +173 -62
  13. package/{src/__tests__/__fixtures__/site-with-doc-label/docusaurus.config.js → lib/frontMatter.d.ts} +4 -8
  14. package/lib/{docFrontMatter.js → frontMatter.js} +16 -6
  15. package/lib/globalData.d.ts +3 -3
  16. package/lib/globalData.js +35 -6
  17. package/lib/index.d.ts +3 -3
  18. package/lib/index.js +135 -140
  19. package/lib/lastUpdate.d.ts +4 -6
  20. package/lib/lastUpdate.js +22 -26
  21. package/lib/markdown/index.d.ts +3 -6
  22. package/lib/markdown/index.js +3 -3
  23. package/lib/markdown/linkify.d.ts +1 -1
  24. package/lib/markdown/linkify.js +7 -4
  25. package/lib/numberPrefix.d.ts +1 -1
  26. package/lib/numberPrefix.js +16 -21
  27. package/lib/options.d.ts +3 -5
  28. package/lib/options.js +55 -19
  29. package/lib/props.d.ts +7 -2
  30. package/lib/props.js +72 -15
  31. package/lib/routes.d.ts +29 -0
  32. package/lib/routes.js +96 -0
  33. package/lib/server-export.d.ts +9 -0
  34. package/lib/server-export.js +22 -0
  35. package/lib/{sidebarItemsGenerator.d.ts → sidebars/generator.d.ts} +1 -6
  36. package/lib/sidebars/generator.js +209 -0
  37. package/lib/sidebars/index.d.ts +13 -0
  38. package/lib/sidebars/index.js +92 -0
  39. package/lib/sidebars/normalization.d.ts +13 -0
  40. package/lib/sidebars/normalization.js +55 -0
  41. package/lib/sidebars/postProcessor.d.ts +8 -0
  42. package/lib/sidebars/postProcessor.js +65 -0
  43. package/lib/sidebars/processor.d.ts +10 -0
  44. package/lib/sidebars/processor.js +90 -0
  45. package/lib/sidebars/types.d.ts +178 -0
  46. package/{src/__tests__/__fixtures__/site-with-autogenerated-sidebar/partialAutogeneratedSidebars2.js → lib/sidebars/types.js} +2 -10
  47. package/lib/sidebars/utils.d.ts +54 -0
  48. package/lib/sidebars/utils.js +255 -0
  49. package/lib/sidebars/validation.d.ts +11 -0
  50. package/lib/sidebars/validation.js +138 -0
  51. package/lib/slug.d.ts +5 -4
  52. package/lib/slug.js +29 -19
  53. package/{src/__tests__/__fixtures__/sidebars/sidebars-first-level-not-category.js → lib/tags.d.ts} +3 -14
  54. package/lib/tags.js +21 -0
  55. package/lib/translations.d.ts +3 -3
  56. package/lib/translations.js +84 -94
  57. package/lib/types.d.ts +13 -171
  58. package/lib/versions/files.d.ts +44 -0
  59. package/lib/versions/files.js +142 -0
  60. package/lib/versions/index.d.ts +36 -0
  61. package/lib/versions/index.js +155 -0
  62. package/lib/versions/validation.d.ts +17 -0
  63. package/lib/versions/validation.js +71 -0
  64. package/package.json +32 -26
  65. package/src/categoryGeneratedIndex.ts +60 -0
  66. package/src/cli.ts +90 -109
  67. package/src/client/docsClientUtils.ts +47 -84
  68. package/src/client/index.ts +103 -0
  69. package/src/constants.ts +4 -2
  70. package/{types.d.ts → src/deps.d.ts} +1 -1
  71. package/src/docs.ts +244 -63
  72. package/src/frontMatter.ts +51 -0
  73. package/src/globalData.ts +57 -7
  74. package/src/index.ts +186 -190
  75. package/src/lastUpdate.ts +26 -33
  76. package/src/markdown/index.ts +10 -16
  77. package/src/markdown/linkify.ts +8 -5
  78. package/src/numberPrefix.ts +19 -26
  79. package/src/options.ts +60 -32
  80. package/src/plugin-content-docs.d.ts +632 -75
  81. package/src/props.ts +109 -22
  82. package/src/routes.ts +159 -0
  83. package/src/server-export.ts +22 -0
  84. package/src/sidebars/README.md +9 -0
  85. package/src/sidebars/generator.ts +292 -0
  86. package/src/sidebars/index.ts +118 -0
  87. package/src/sidebars/normalization.ts +85 -0
  88. package/src/sidebars/postProcessor.ts +89 -0
  89. package/src/sidebars/processor.ts +139 -0
  90. package/src/sidebars/types.ts +275 -0
  91. package/src/sidebars/utils.ts +391 -0
  92. package/src/sidebars/validation.ts +174 -0
  93. package/src/slug.ts +42 -23
  94. package/src/tags.ts +20 -0
  95. package/src/translations.ts +124 -117
  96. package/src/types.ts +18 -231
  97. package/src/versions/files.ts +220 -0
  98. package/src/versions/index.ts +247 -0
  99. package/src/versions/validation.ts +113 -0
  100. package/lib/.tsbuildinfo +0 -4673
  101. package/lib/docFrontMatter.d.ts +0 -21
  102. package/lib/sidebarItemsGenerator.js +0 -211
  103. package/lib/sidebars.d.ts +0 -42
  104. package/lib/sidebars.js +0 -309
  105. package/lib/theme/hooks/useDocs.d.ts +0 -20
  106. package/lib/theme/hooks/useDocs.js +0 -72
  107. package/lib/versions.d.ts +0 -16
  108. package/lib/versions.js +0 -287
  109. package/src/__tests__/__fixtures__/bad-id-site/docs/invalid-id.md +0 -5
  110. package/src/__tests__/__fixtures__/bad-slug-on-doc-home-site/docs/docWithSlug.md +0 -5
  111. package/src/__tests__/__fixtures__/empty-site/docusaurus.config.js +0 -16
  112. package/src/__tests__/__fixtures__/empty-site/sidebars.json +0 -1
  113. package/src/__tests__/__fixtures__/sidebars/sidebars-category-shorthand.js +0 -34
  114. package/src/__tests__/__fixtures__/sidebars/sidebars-category-wrong-items.json +0 -11
  115. package/src/__tests__/__fixtures__/sidebars/sidebars-category-wrong-label.json +0 -11
  116. package/src/__tests__/__fixtures__/sidebars/sidebars-category.js +0 -44
  117. package/src/__tests__/__fixtures__/sidebars/sidebars-collapsed-first-level.json +0 -20
  118. package/src/__tests__/__fixtures__/sidebars/sidebars-collapsed.json +0 -21
  119. package/src/__tests__/__fixtures__/sidebars/sidebars-doc-id-not-string.json +0 -10
  120. package/src/__tests__/__fixtures__/sidebars/sidebars-link-wrong-href.json +0 -11
  121. package/src/__tests__/__fixtures__/sidebars/sidebars-link-wrong-label.json +0 -11
  122. package/src/__tests__/__fixtures__/sidebars/sidebars-link.json +0 -11
  123. package/src/__tests__/__fixtures__/sidebars/sidebars-unknown-type.json +0 -14
  124. package/src/__tests__/__fixtures__/sidebars/sidebars-wrong-field.json +0 -20
  125. package/src/__tests__/__fixtures__/sidebars/sidebars.json +0 -20
  126. package/src/__tests__/__fixtures__/simple-site/docs/foo/bar.md +0 -69
  127. package/src/__tests__/__fixtures__/simple-site/docs/foo/baz.md +0 -67
  128. package/src/__tests__/__fixtures__/simple-site/docs/headingAsTitle.md +0 -1
  129. package/src/__tests__/__fixtures__/simple-site/docs/hello.md +0 -52
  130. package/src/__tests__/__fixtures__/simple-site/docs/ipsum.md +0 -5
  131. package/src/__tests__/__fixtures__/simple-site/docs/lorem.md +0 -6
  132. package/src/__tests__/__fixtures__/simple-site/docs/rootAbsoluteSlug.md +0 -5
  133. package/src/__tests__/__fixtures__/simple-site/docs/rootRelativeSlug.md +0 -5
  134. package/src/__tests__/__fixtures__/simple-site/docs/rootResolvedSlug.md +0 -5
  135. package/src/__tests__/__fixtures__/simple-site/docs/rootTryToEscapeSlug.md +0 -5
  136. package/src/__tests__/__fixtures__/simple-site/docs/slugs/absoluteSlug.md +0 -5
  137. package/src/__tests__/__fixtures__/simple-site/docs/slugs/relativeSlug.md +0 -5
  138. package/src/__tests__/__fixtures__/simple-site/docs/slugs/resolvedSlug.md +0 -5
  139. package/src/__tests__/__fixtures__/simple-site/docs/slugs/tryToEscapeSlug.md +0 -5
  140. package/src/__tests__/__fixtures__/simple-site/docusaurus.config.js +0 -14
  141. package/src/__tests__/__fixtures__/simple-site/sidebars.json +0 -23
  142. package/src/__tests__/__fixtures__/simple-site/wrong-sidebars.json +0 -7
  143. package/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/0-getting-started.md +0 -3
  144. package/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/1-installation.md +0 -3
  145. package/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/3-API/00_api-overview.md +0 -3
  146. package/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/3-API/01_Core APIs/0 --- Client API.md +0 -1
  147. package/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/3-API/01_Core APIs/1 --- Server API.md +0 -1
  148. package/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/3-API/02_Extension APIs/0. Plugin API.md +0 -1
  149. package/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/3-API/02_Extension APIs/1. Theme API.md +0 -1
  150. package/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/3-API/02_Extension APIs/_category_.yml +0 -1
  151. package/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/3-API/03_api-end.md +0 -3
  152. package/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/3-API/_category_.json +0 -3
  153. package/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/Guides/0-guide2.5.md +0 -8
  154. package/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/Guides/02-guide2.md +0 -7
  155. package/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/Guides/_category_.json +0 -3
  156. package/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/Guides/a-guide4.md +0 -7
  157. package/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/Guides/b-guide5.md +0 -7
  158. package/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/Guides/guide3.md +0 -8
  159. package/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docs/Guides/z-guide1.md +0 -8
  160. package/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docusaurus.config.js +0 -14
  161. package/src/__tests__/__fixtures__/site-with-autogenerated-sidebar/partialAutogeneratedSidebars.js +0 -23
  162. package/src/__tests__/__fixtures__/site-with-doc-label/docs/hello-1.md +0 -7
  163. package/src/__tests__/__fixtures__/site-with-doc-label/docs/hello-2.md +0 -8
  164. package/src/__tests__/__fixtures__/site-with-doc-label/sidebars.json +0 -14
  165. package/src/__tests__/__fixtures__/versioned-site/community/team.md +0 -1
  166. package/src/__tests__/__fixtures__/versioned-site/community_sidebars.json +0 -3
  167. package/src/__tests__/__fixtures__/versioned-site/community_versioned_docs/version-1.0.0/team.md +0 -1
  168. package/src/__tests__/__fixtures__/versioned-site/community_versioned_sidebars/version-1.0.0-sidebars.json +0 -3
  169. package/src/__tests__/__fixtures__/versioned-site/community_versions.json +0 -1
  170. package/src/__tests__/__fixtures__/versioned-site/docs/foo/bar.md +0 -4
  171. package/src/__tests__/__fixtures__/versioned-site/docs/hello.md +0 -1
  172. package/src/__tests__/__fixtures__/versioned-site/docs/slugs/absoluteSlug.md +0 -5
  173. package/src/__tests__/__fixtures__/versioned-site/docs/slugs/relativeSlug.md +0 -5
  174. package/src/__tests__/__fixtures__/versioned-site/docs/slugs/resolvedSlug.md +0 -5
  175. package/src/__tests__/__fixtures__/versioned-site/docs/slugs/tryToEscapeSlug.md +0 -5
  176. package/src/__tests__/__fixtures__/versioned-site/docusaurus.config.js +0 -18
  177. package/src/__tests__/__fixtures__/versioned-site/i18n/en/docusaurus-plugin-content-docs/version-1.0.0/hello.md +0 -1
  178. package/src/__tests__/__fixtures__/versioned-site/i18n/en/docusaurus-plugin-content-docs-community/current/team.md +0 -5
  179. package/src/__tests__/__fixtures__/versioned-site/i18n/fr/docusaurus-plugin-content-docs/version-1.0.0/hello.md +0 -1
  180. package/src/__tests__/__fixtures__/versioned-site/sidebars.json +0 -10
  181. package/src/__tests__/__fixtures__/versioned-site/versioned_docs/version-1.0.0/foo/bar.md +0 -4
  182. package/src/__tests__/__fixtures__/versioned-site/versioned_docs/version-1.0.0/foo/baz.md +0 -1
  183. package/src/__tests__/__fixtures__/versioned-site/versioned_docs/version-1.0.0/hello.md +0 -1
  184. package/src/__tests__/__fixtures__/versioned-site/versioned_docs/version-1.0.1/foo/bar.md +0 -1
  185. package/src/__tests__/__fixtures__/versioned-site/versioned_docs/version-1.0.1/hello.md +0 -1
  186. package/src/__tests__/__fixtures__/versioned-site/versioned_docs/version-withSlugs/rootAbsoluteSlug.md +0 -5
  187. package/src/__tests__/__fixtures__/versioned-site/versioned_docs/version-withSlugs/rootRelativeSlug.md +0 -5
  188. package/src/__tests__/__fixtures__/versioned-site/versioned_docs/version-withSlugs/rootResolvedSlug.md +0 -5
  189. package/src/__tests__/__fixtures__/versioned-site/versioned_docs/version-withSlugs/rootTryToEscapeSlug.md +0 -5
  190. package/src/__tests__/__fixtures__/versioned-site/versioned_docs/version-withSlugs/slugs/absoluteSlug.md +0 -5
  191. package/src/__tests__/__fixtures__/versioned-site/versioned_docs/version-withSlugs/slugs/relativeSlug.md +0 -5
  192. package/src/__tests__/__fixtures__/versioned-site/versioned_docs/version-withSlugs/slugs/resolvedSlug.md +0 -5
  193. package/src/__tests__/__fixtures__/versioned-site/versioned_docs/version-withSlugs/slugs/tryToEscapeSlug.md +0 -5
  194. package/src/__tests__/__fixtures__/versioned-site/versioned_sidebars/version-1.0.0-sidebars.json +0 -11
  195. package/src/__tests__/__fixtures__/versioned-site/versioned_sidebars/version-1.0.1-sidebars.json +0 -10
  196. package/src/__tests__/__fixtures__/versioned-site/versioned_sidebars/version-withSlugs-sidebars.json +0 -5
  197. package/src/__tests__/__fixtures__/versioned-site/versions.json +0 -5
  198. package/src/__tests__/__snapshots__/cli.test.ts.snap +0 -90
  199. package/src/__tests__/__snapshots__/index.test.ts.snap +0 -1907
  200. package/src/__tests__/__snapshots__/sidebars.test.ts.snap +0 -218
  201. package/src/__tests__/__snapshots__/translations.test.ts.snap +0 -487
  202. package/src/__tests__/cli.test.ts +0 -333
  203. package/src/__tests__/docFrontMatter.test.ts +0 -204
  204. package/src/__tests__/docs.test.ts +0 -875
  205. package/src/__tests__/index.test.ts +0 -1831
  206. package/src/__tests__/lastUpdate.test.ts +0 -68
  207. package/src/__tests__/numberPrefix.test.ts +0 -199
  208. package/src/__tests__/options.test.ts +0 -232
  209. package/src/__tests__/sidebarItemsGenerator.test.ts +0 -336
  210. package/src/__tests__/sidebars.test.ts +0 -638
  211. package/src/__tests__/slug.test.ts +0 -109
  212. package/src/__tests__/translations.test.ts +0 -159
  213. package/src/__tests__/versions.test.ts +0 -718
  214. package/src/client/__tests__/docsClientUtils.test.ts +0 -372
  215. package/src/docFrontMatter.ts +0 -53
  216. package/src/markdown/__tests__/__fixtures__/docs/doc-localized.md +0 -1
  217. package/src/markdown/__tests__/__fixtures__/docs/doc1.md +0 -13
  218. package/src/markdown/__tests__/__fixtures__/docs/doc2.md +0 -12
  219. package/src/markdown/__tests__/__fixtures__/docs/doc4.md +0 -19
  220. package/src/markdown/__tests__/__fixtures__/docs/doc5.md +0 -6
  221. package/src/markdown/__tests__/__fixtures__/docs/subdir/doc3.md +0 -3
  222. package/src/markdown/__tests__/__fixtures__/versioned_docs/version-1.0.0/doc2.md +0 -7
  223. package/src/markdown/__tests__/__fixtures__/versioned_docs/version-1.0.0/subdir/doc1.md +0 -3
  224. package/src/markdown/__tests__/__snapshots__/linkify.test.ts.snap +0 -82
  225. package/src/markdown/__tests__/linkify.test.ts +0 -190
  226. package/src/sidebarItemsGenerator.ts +0 -307
  227. package/src/sidebars.ts +0 -489
  228. package/src/theme/hooks/useDocs.ts +0 -99
  229. package/src/versions.ts +0 -511
  230. package/tsconfig.json +0 -9
package/lib/docs.js CHANGED
@@ -6,24 +6,24 @@
6
6
  * LICENSE file in the root directory of this source tree.
7
7
  */
8
8
  Object.defineProperty(exports, "__esModule", { value: true });
9
- exports.processDocMetadata = exports.readVersionDocs = exports.readDocFile = void 0;
9
+ exports.createDocsByIdIndex = exports.getDocIds = exports.toCategoryIndexMatcherParam = exports.isCategoryIndex = exports.getMainDocId = exports.addDocNavigation = exports.processDocMetadata = exports.readVersionDocs = exports.readDocFile = void 0;
10
10
  const tslib_1 = require("tslib");
11
11
  const path_1 = tslib_1.__importDefault(require("path"));
12
12
  const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
13
+ const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
13
14
  const utils_1 = require("@docusaurus/utils");
14
15
  const lastUpdate_1 = require("./lastUpdate");
15
16
  const slug_1 = tslib_1.__importDefault(require("./slug"));
16
17
  const constants_1 = require("./constants");
17
- const globby_1 = tslib_1.__importDefault(require("globby"));
18
- const versions_1 = require("./versions");
19
18
  const numberPrefix_1 = require("./numberPrefix");
20
- const docFrontMatter_1 = require("./docFrontMatter");
19
+ const frontMatter_1 = require("./frontMatter");
20
+ const utils_2 = require("./sidebars/utils");
21
21
  async function readLastUpdateData(filePath, options) {
22
22
  const { showLastUpdateAuthor, showLastUpdateTime } = options;
23
23
  if (showLastUpdateAuthor || showLastUpdateTime) {
24
24
  // Use fake data in dev for faster development.
25
25
  const fileLastUpdateData = process.env.NODE_ENV === 'production'
26
- ? await lastUpdate_1.getFileLastUpdate(filePath)
26
+ ? await (0, lastUpdate_1.getFileLastUpdate)(filePath)
27
27
  : {
28
28
  author: 'Author',
29
29
  timestamp: 1539502055,
@@ -39,7 +39,7 @@ async function readLastUpdateData(filePath, options) {
39
39
  return {};
40
40
  }
41
41
  async function readDocFile(versionMetadata, source, options) {
42
- const contentPath = await utils_1.getFolderContainingFile(versions_1.getDocsDirPaths(versionMetadata), source);
42
+ const contentPath = await (0, utils_1.getFolderContainingFile)((0, utils_1.getContentPathList)(versionMetadata), source);
43
43
  const filePath = path_1.default.join(contentPath, source);
44
44
  const [content, lastUpdate] = await Promise.all([
45
45
  fs_extra_1.default.readFile(filePath, 'utf-8'),
@@ -49,38 +49,41 @@ async function readDocFile(versionMetadata, source, options) {
49
49
  }
50
50
  exports.readDocFile = readDocFile;
51
51
  async function readVersionDocs(versionMetadata, options) {
52
- const sources = await globby_1.default(options.include, {
52
+ const sources = await (0, utils_1.Globby)(options.include, {
53
53
  cwd: versionMetadata.contentPath,
54
+ ignore: options.exclude,
54
55
  });
55
56
  return Promise.all(sources.map((source) => readDocFile(versionMetadata, source, options)));
56
57
  }
57
58
  exports.readVersionDocs = readVersionDocs;
58
- function processDocMetadata({ docFile, versionMetadata, context, options, }) {
59
- var _a, _b, _c, _d, _e;
59
+ /** Docs with draft front matter are only considered draft in production. */
60
+ function isDraftForEnvironment({ env, frontMatter, }) {
61
+ return (env === 'production' && frontMatter.draft) ?? false;
62
+ }
63
+ function doProcessDocMetadata({ docFile, versionMetadata, context, options, env, }) {
60
64
  const { source, content, lastUpdate, contentPath, filePath } = docFile;
61
- const { homePageId } = options;
62
65
  const { siteDir, i18n } = context;
63
- const { frontMatter: unsafeFrontMatter, contentTitle, excerpt, } = utils_1.parseMarkdownString(content);
64
- const frontMatter = docFrontMatter_1.validateDocFrontMatter(unsafeFrontMatter);
65
- const { sidebar_label: sidebarLabel, custom_edit_url: customEditURL,
66
- // Strip number prefixes by default (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc) by default,
67
- // but allow to disable this behavior with frontmatterr
68
- parse_number_prefixes = true, } = frontMatter;
69
- // ex: api/plugins/myDoc -> myDoc
70
- // ex: myDoc -> myDoc
66
+ const { frontMatter: unsafeFrontMatter, contentTitle, excerpt, } = (0, utils_1.parseMarkdownString)(content);
67
+ const frontMatter = (0, frontMatter_1.validateDocFrontMatter)(unsafeFrontMatter);
68
+ const { custom_edit_url: customEditURL,
69
+ // Strip number prefixes by default
70
+ // (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc)
71
+ // but allow to disable this behavior with front matter
72
+ parse_number_prefixes: parseNumberPrefixes = true, } = frontMatter;
73
+ // E.g. api/plugins/myDoc -> myDoc; myDoc -> myDoc
71
74
  const sourceFileNameWithoutExtension = path_1.default.basename(source, path_1.default.extname(source));
72
- // ex: api/plugins/myDoc -> api/plugins
73
- // ex: myDoc -> .
75
+ // E.g. api/plugins/myDoc -> api/plugins; myDoc -> .
74
76
  const sourceDirName = path_1.default.dirname(source);
75
- const { filename: unprefixedFileName, numberPrefix } = parse_number_prefixes
77
+ const { filename: unprefixedFileName, numberPrefix } = parseNumberPrefixes
76
78
  ? options.numberPrefixParser(sourceFileNameWithoutExtension)
77
79
  : { filename: sourceFileNameWithoutExtension, numberPrefix: undefined };
78
- const baseID = (_a = frontMatter.id) !== null && _a !== void 0 ? _a : unprefixedFileName;
80
+ const baseID = frontMatter.id ?? unprefixedFileName;
79
81
  if (baseID.includes('/')) {
80
- throw new Error(`Document id [${baseID}] cannot include "/".`);
82
+ throw new Error(`Document id "${baseID}" cannot include slash.`);
81
83
  }
82
- // For autogenerated sidebars, sidebar position can come from filename number prefix or frontmatter
83
- const sidebarPosition = (_b = frontMatter.sidebar_position) !== null && _b !== void 0 ? _b : numberPrefix;
84
+ // For autogenerated sidebars, sidebar position can come from filename number
85
+ // prefix or front matter
86
+ const sidebarPosition = frontMatter.sidebar_position ?? numberPrefix;
84
87
  // TODO legacy retrocompatibility
85
88
  // The same doc in 2 distinct version could keep the same id,
86
89
  // we just need to namespace the data by version
@@ -88,14 +91,14 @@ function processDocMetadata({ docFile, versionMetadata, context, options, }) {
88
91
  ? undefined
89
92
  : `version-${versionMetadata.versionName}`;
90
93
  // TODO legacy retrocompatibility
91
- // I think it's bad to affect the frontmatter id with the dirname?
94
+ // I think it's bad to affect the front matter id with the dirname?
92
95
  function computeDirNameIdPrefix() {
93
96
  if (sourceDirName === '.') {
94
97
  return undefined;
95
98
  }
96
99
  // Eventually remove the number prefixes from intermediate directories
97
- return parse_number_prefixes
98
- ? numberPrefix_1.stripPathNumberPrefixes(sourceDirName, options.numberPrefixParser)
100
+ return parseNumberPrefixes
101
+ ? (0, numberPrefix_1.stripPathNumberPrefixes)(sourceDirName, options.numberPrefixParser)
99
102
  : sourceDirName;
100
103
  }
101
104
  const unversionedId = [computeDirNameIdPrefix(), baseID]
@@ -104,34 +107,27 @@ function processDocMetadata({ docFile, versionMetadata, context, options, }) {
104
107
  // TODO is versioning the id very useful in practice?
105
108
  // legacy versioned id, requires a breaking change to modify this
106
109
  const id = [versionIdPrefix, unversionedId].filter(Boolean).join('/');
107
- // TODO remove soon, deprecated homePageId
108
- const isDocsHomePage = unversionedId === (homePageId !== null && homePageId !== void 0 ? homePageId : '_index');
109
- if (frontMatter.slug && isDocsHomePage) {
110
- throw new Error(`The docs homepage (homePageId=${homePageId}) is not allowed to have a frontmatter slug=${frontMatter.slug} => you have to choose either homePageId or slug, not both`);
111
- }
112
- const docSlug = isDocsHomePage
113
- ? '/'
114
- : slug_1.default({
115
- baseID,
116
- dirName: sourceDirName,
117
- frontmatterSlug: frontMatter.slug,
118
- stripDirNumberPrefixes: parse_number_prefixes,
119
- numberPrefixParser: options.numberPrefixParser,
120
- });
121
- // TODO expose both headingTitle+metaTitle to theme?
122
- // Different fallbacks order on purpose!
123
- // See https://github.com/facebook/docusaurus/issues/4665#issuecomment-825831367
124
- const headingTitle = (_c = contentTitle !== null && contentTitle !== void 0 ? contentTitle : frontMatter.title) !== null && _c !== void 0 ? _c : baseID;
125
- // const metaTitle: string = frontMatter.title ?? contentTitle ?? baseID;
126
- const description = (_e = (_d = frontMatter.description) !== null && _d !== void 0 ? _d : excerpt) !== null && _e !== void 0 ? _e : '';
127
- const permalink = utils_1.normalizeUrl([versionMetadata.versionPath, docSlug]);
110
+ const docSlug = (0, slug_1.default)({
111
+ baseID,
112
+ source,
113
+ sourceDirName,
114
+ frontMatterSlug: frontMatter.slug,
115
+ stripDirNumberPrefixes: parseNumberPrefixes,
116
+ numberPrefixParser: options.numberPrefixParser,
117
+ });
118
+ // Note: the title is used by default for page title, sidebar label,
119
+ // pagination buttons... frontMatter.title should be used in priority over
120
+ // contentTitle (because it can contain markdown/JSX syntax)
121
+ const title = frontMatter.title ?? contentTitle ?? baseID;
122
+ const description = frontMatter.description ?? excerpt ?? '';
123
+ const permalink = (0, utils_1.normalizeUrl)([versionMetadata.path, docSlug]);
128
124
  function getDocEditUrl() {
129
125
  const relativeFilePath = path_1.default.relative(contentPath, filePath);
130
126
  if (typeof options.editUrl === 'function') {
131
127
  return options.editUrl({
132
128
  version: versionMetadata.versionName,
133
- versionDocsDirPath: utils_1.posixPath(path_1.default.relative(siteDir, versionMetadata.contentPath)),
134
- docPath: utils_1.posixPath(relativeFilePath),
129
+ versionDocsDirPath: (0, utils_1.posixPath)(path_1.default.relative(siteDir, versionMetadata.contentPath)),
130
+ docPath: (0, utils_1.posixPath)(relativeFilePath),
135
131
  permalink,
136
132
  locale: context.i18n.currentLocale,
137
133
  });
@@ -139,14 +135,13 @@ function processDocMetadata({ docFile, versionMetadata, context, options, }) {
139
135
  else if (typeof options.editUrl === 'string') {
140
136
  const isLocalized = contentPath === versionMetadata.contentPathLocalized;
141
137
  const baseVersionEditUrl = isLocalized && options.editLocalizedFiles
142
- ? versionMetadata.versionEditUrlLocalized
143
- : versionMetadata.versionEditUrl;
144
- return utils_1.getEditUrl(relativeFilePath, baseVersionEditUrl);
145
- }
146
- else {
147
- return undefined;
138
+ ? versionMetadata.editUrlLocalized
139
+ : versionMetadata.editUrl;
140
+ return (0, utils_1.getEditUrl)(relativeFilePath, baseVersionEditUrl);
148
141
  }
142
+ return undefined;
149
143
  }
144
+ const draft = isDraftForEnvironment({ env, frontMatter });
150
145
  // Assign all of object properties during instantiation (if possible) for
151
146
  // NodeJS optimization.
152
147
  // Adding properties to object after instantiation will cause hidden
@@ -154,23 +149,139 @@ function processDocMetadata({ docFile, versionMetadata, context, options, }) {
154
149
  return {
155
150
  unversionedId,
156
151
  id,
157
- isDocsHomePage,
158
- title: headingTitle,
152
+ title,
159
153
  description,
160
- source: utils_1.aliasedSitePath(filePath, siteDir),
154
+ source: (0, utils_1.aliasedSitePath)(filePath, siteDir),
161
155
  sourceDirName,
162
156
  slug: docSlug,
163
157
  permalink,
158
+ draft,
164
159
  editUrl: customEditURL !== undefined ? customEditURL : getDocEditUrl(),
160
+ tags: (0, utils_1.normalizeFrontMatterTags)(versionMetadata.tagsPath, frontMatter.tags),
165
161
  version: versionMetadata.versionName,
166
162
  lastUpdatedBy: lastUpdate.lastUpdatedBy,
167
163
  lastUpdatedAt: lastUpdate.lastUpdatedAt,
168
164
  formattedLastUpdatedAt: lastUpdate.lastUpdatedAt
169
- ? new Intl.DateTimeFormat(i18n.currentLocale).format(lastUpdate.lastUpdatedAt * 1000)
165
+ ? new Intl.DateTimeFormat(i18n.currentLocale, {
166
+ calendar: i18n.localeConfigs[i18n.currentLocale].calendar,
167
+ }).format(lastUpdate.lastUpdatedAt * 1000)
170
168
  : undefined,
171
- sidebar_label: sidebarLabel,
172
169
  sidebarPosition,
173
170
  frontMatter,
174
171
  };
175
172
  }
173
+ function processDocMetadata(args) {
174
+ try {
175
+ return doProcessDocMetadata(args);
176
+ }
177
+ catch (err) {
178
+ logger_1.default.error `Can't process doc metadata for doc at path path=${args.docFile.filePath} in version name=${args.versionMetadata.versionName}`;
179
+ throw err;
180
+ }
181
+ }
176
182
  exports.processDocMetadata = processDocMetadata;
183
+ function addDocNavigation(docsBase, sidebarsUtils, sidebarFilePath) {
184
+ const docsById = createDocsByIdIndex(docsBase);
185
+ sidebarsUtils.checkSidebarsDocIds(docsBase.flatMap(getDocIds), sidebarFilePath);
186
+ // Add sidebar/next/previous to the docs
187
+ function addNavData(doc) {
188
+ const navigation = sidebarsUtils.getDocNavigation(doc.unversionedId, doc.id, doc.frontMatter.displayed_sidebar);
189
+ const toNavigationLinkByDocId = (docId, type) => {
190
+ if (!docId) {
191
+ return undefined;
192
+ }
193
+ const navDoc = docsById[docId];
194
+ if (!navDoc) {
195
+ // This could only happen if user provided the ID through front matter
196
+ throw new Error(`Error when loading ${doc.id} in ${doc.sourceDirName}: the pagination_${type} front matter points to a non-existent ID ${docId}.`);
197
+ }
198
+ return (0, utils_2.toDocNavigationLink)(navDoc);
199
+ };
200
+ const previous = doc.frontMatter.pagination_prev !== undefined
201
+ ? toNavigationLinkByDocId(doc.frontMatter.pagination_prev, 'prev')
202
+ : (0, utils_2.toNavigationLink)(navigation.previous, docsById);
203
+ const next = doc.frontMatter.pagination_next !== undefined
204
+ ? toNavigationLinkByDocId(doc.frontMatter.pagination_next, 'next')
205
+ : (0, utils_2.toNavigationLink)(navigation.next, docsById);
206
+ return { ...doc, sidebar: navigation.sidebarName, previous, next };
207
+ }
208
+ const docsWithNavigation = docsBase.map(addNavData);
209
+ // Sort to ensure consistent output for tests
210
+ docsWithNavigation.sort((a, b) => a.id.localeCompare(b.id));
211
+ return docsWithNavigation;
212
+ }
213
+ exports.addDocNavigation = addDocNavigation;
214
+ /**
215
+ * The "main doc" is the "version entry point"
216
+ * We browse this doc by clicking on a version:
217
+ * - the "home" doc (at '/docs/')
218
+ * - the first doc of the first sidebar
219
+ * - a random doc (if no docs are in any sidebar... edge case)
220
+ */
221
+ function getMainDocId({ docs, sidebarsUtils, }) {
222
+ function getMainDoc() {
223
+ const versionHomeDoc = docs.find((doc) => doc.slug === '/');
224
+ const firstDocIdOfFirstSidebar = sidebarsUtils.getFirstDocIdOfFirstSidebar();
225
+ if (versionHomeDoc) {
226
+ return versionHomeDoc;
227
+ }
228
+ else if (firstDocIdOfFirstSidebar) {
229
+ return docs.find((doc) => doc.id === firstDocIdOfFirstSidebar ||
230
+ doc.unversionedId === firstDocIdOfFirstSidebar);
231
+ }
232
+ return docs[0];
233
+ }
234
+ return getMainDoc().unversionedId;
235
+ }
236
+ exports.getMainDocId = getMainDocId;
237
+ // By convention, Docusaurus considers some docs are "indexes":
238
+ // - index.md
239
+ // - readme.md
240
+ // - <folder>/<folder>.md
241
+ //
242
+ // This function is the default implementation of this convention
243
+ //
244
+ // Those index docs produce a different behavior
245
+ // - Slugs do not end with a weird "/index" suffix
246
+ // - Auto-generated sidebar categories link to them as intro
247
+ const isCategoryIndex = ({ fileName, directories, }) => {
248
+ const eligibleDocIndexNames = [
249
+ 'index',
250
+ 'readme',
251
+ directories[0]?.toLowerCase(),
252
+ ];
253
+ return eligibleDocIndexNames.includes(fileName.toLowerCase());
254
+ };
255
+ exports.isCategoryIndex = isCategoryIndex;
256
+ /**
257
+ * `guides/sidebar/autogenerated.md` ->
258
+ * `'autogenerated', '.md', ['sidebar', 'guides']`
259
+ */
260
+ function toCategoryIndexMatcherParam({ source, sourceDirName, }) {
261
+ // source + sourceDirName are always posix-style
262
+ return {
263
+ fileName: path_1.default.posix.parse(source).name,
264
+ extension: path_1.default.posix.parse(source).ext,
265
+ directories: sourceDirName.split(path_1.default.posix.sep).reverse(),
266
+ };
267
+ }
268
+ exports.toCategoryIndexMatcherParam = toCategoryIndexMatcherParam;
269
+ // Return both doc ids
270
+ // TODO legacy retro-compatibility due to old versioned sidebars using
271
+ // versioned doc ids ("id" should be removed & "versionedId" should be renamed
272
+ // to "id")
273
+ function getDocIds(doc) {
274
+ return [doc.unversionedId, doc.id];
275
+ }
276
+ exports.getDocIds = getDocIds;
277
+ // Docs are indexed by both versioned and unversioned ids at the same time
278
+ // TODO legacy retro-compatibility due to old versioned sidebars using
279
+ // versioned doc ids ("id" should be removed & "versionedId" should be renamed
280
+ // to "id")
281
+ function createDocsByIdIndex(docs) {
282
+ return Object.fromEntries(docs.flatMap((doc) => [
283
+ [doc.unversionedId, doc],
284
+ [doc.id, doc],
285
+ ]));
286
+ }
287
+ exports.createDocsByIdIndex = createDocsByIdIndex;
@@ -4,11 +4,7 @@
4
4
  * This source code is licensed under the MIT license found in the
5
5
  * LICENSE file in the root directory of this source tree.
6
6
  */
7
-
8
- module.exports = {
9
- title: 'My Site',
10
- tagline: 'The tagline of my site',
11
- url: 'https://your-docusaurus-test-site.com',
12
- baseUrl: '/',
13
- favicon: 'img/favicon.ico',
14
- };
7
+ import type { DocFrontMatter } from '@docusaurus/plugin-content-docs';
8
+ export declare function validateDocFrontMatter(frontMatter: {
9
+ [key: string]: unknown;
10
+ }): DocFrontMatter;
@@ -7,27 +7,37 @@
7
7
  */
8
8
  Object.defineProperty(exports, "__esModule", { value: true });
9
9
  exports.validateDocFrontMatter = void 0;
10
- /* eslint-disable camelcase */
11
10
  const utils_validation_1 = require("@docusaurus/utils-validation");
12
11
  // NOTE: we don't add any default value on purpose here
13
- // We don't want default values to magically appear in doc metadatas and props
12
+ // We don't want default values to magically appear in doc metadata and props
14
13
  // While the user did not provide those values explicitly
15
14
  // We use default values in code instead
16
15
  const DocFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
17
16
  id: utils_validation_1.JoiFrontMatter.string(),
17
+ // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
18
18
  title: utils_validation_1.JoiFrontMatter.string().allow(''),
19
19
  hide_title: utils_validation_1.JoiFrontMatter.boolean(),
20
20
  hide_table_of_contents: utils_validation_1.JoiFrontMatter.boolean(),
21
21
  keywords: utils_validation_1.JoiFrontMatter.array().items(utils_validation_1.JoiFrontMatter.string().required()),
22
- image: utils_validation_1.JoiFrontMatter.string().uri({ allowRelative: false }),
22
+ image: utils_validation_1.URISchema,
23
+ // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
23
24
  description: utils_validation_1.JoiFrontMatter.string().allow(''),
24
25
  slug: utils_validation_1.JoiFrontMatter.string(),
25
26
  sidebar_label: utils_validation_1.JoiFrontMatter.string(),
26
- sidebar_position: utils_validation_1.JoiFrontMatter.number().min(0),
27
- custom_edit_url: utils_validation_1.JoiFrontMatter.string().uri({ allowRelative: true }).allow('', null),
27
+ sidebar_position: utils_validation_1.JoiFrontMatter.number(),
28
+ sidebar_class_name: utils_validation_1.JoiFrontMatter.string(),
29
+ sidebar_custom_props: utils_validation_1.JoiFrontMatter.object().unknown(),
30
+ displayed_sidebar: utils_validation_1.JoiFrontMatter.string().allow(null),
31
+ tags: utils_validation_1.FrontMatterTagsSchema,
32
+ pagination_label: utils_validation_1.JoiFrontMatter.string(),
33
+ custom_edit_url: utils_validation_1.URISchema.allow('', null),
28
34
  parse_number_prefixes: utils_validation_1.JoiFrontMatter.boolean(),
35
+ pagination_next: utils_validation_1.JoiFrontMatter.string().allow(null),
36
+ pagination_prev: utils_validation_1.JoiFrontMatter.string().allow(null),
37
+ draft: utils_validation_1.JoiFrontMatter.boolean(),
38
+ ...utils_validation_1.FrontMatterTOCHeadingLevels,
29
39
  }).unknown();
30
40
  function validateDocFrontMatter(frontMatter) {
31
- return utils_validation_1.validateFrontMatter(frontMatter, DocFrontMatterSchema);
41
+ return (0, utils_validation_1.validateFrontMatter)(frontMatter, DocFrontMatterSchema);
32
42
  }
33
43
  exports.validateDocFrontMatter = validateDocFrontMatter;
@@ -4,6 +4,6 @@
4
4
  * This source code is licensed under the MIT license found in the
5
5
  * LICENSE file in the root directory of this source tree.
6
6
  */
7
- import { DocMetadata, GlobalDoc, LoadedVersion, GlobalVersion } from './types';
8
- export declare function toGlobalDataDoc(doc: DocMetadata): GlobalDoc;
9
- export declare function toGlobalDataVersion(version: LoadedVersion): GlobalVersion;
7
+ import type { FullVersion } from './types';
8
+ import type { GlobalVersion } from '@docusaurus/plugin-content-docs/client';
9
+ export declare function toGlobalDataVersion(version: FullVersion): GlobalVersion;
package/lib/globalData.js CHANGED
@@ -6,7 +6,10 @@
6
6
  * LICENSE file in the root directory of this source tree.
7
7
  */
8
8
  Object.defineProperty(exports, "__esModule", { value: true });
9
- exports.toGlobalDataVersion = exports.toGlobalDataDoc = void 0;
9
+ exports.toGlobalDataVersion = void 0;
10
+ const tslib_1 = require("tslib");
11
+ const lodash_1 = tslib_1.__importDefault(require("lodash"));
12
+ const docs_1 = require("./docs");
10
13
  function toGlobalDataDoc(doc) {
11
14
  return {
12
15
  id: doc.unversionedId,
@@ -14,15 +17,41 @@ function toGlobalDataDoc(doc) {
14
17
  sidebar: doc.sidebar,
15
18
  };
16
19
  }
17
- exports.toGlobalDataDoc = toGlobalDataDoc;
20
+ function toGlobalDataGeneratedIndex(doc) {
21
+ return {
22
+ id: doc.slug,
23
+ path: doc.permalink,
24
+ sidebar: doc.sidebar,
25
+ };
26
+ }
27
+ function toGlobalSidebars(sidebars, version) {
28
+ return lodash_1.default.mapValues(sidebars, (sidebar, sidebarId) => {
29
+ const firstLink = version.sidebarsUtils.getFirstLink(sidebarId);
30
+ if (!firstLink) {
31
+ return {};
32
+ }
33
+ return {
34
+ link: {
35
+ path: firstLink.type === 'generated-index'
36
+ ? firstLink.permalink
37
+ : version.docs.find((doc) => doc.id === firstLink.id || doc.unversionedId === firstLink.id).permalink,
38
+ label: firstLink.label,
39
+ },
40
+ };
41
+ });
42
+ }
18
43
  function toGlobalDataVersion(version) {
19
44
  return {
20
45
  name: version.versionName,
21
- label: version.versionLabel,
46
+ label: version.label,
22
47
  isLast: version.isLast,
23
- path: version.versionPath,
24
- mainDocId: version.mainDocId,
25
- docs: version.docs.map(toGlobalDataDoc),
48
+ path: version.path,
49
+ mainDocId: (0, docs_1.getMainDocId)(version),
50
+ docs: version.docs
51
+ .map(toGlobalDataDoc)
52
+ .concat(version.categoryGeneratedIndices.map(toGlobalDataGeneratedIndex)),
53
+ draftIds: version.drafts.map((doc) => doc.unversionedId),
54
+ sidebars: toGlobalSidebars(version.sidebars, version),
26
55
  };
27
56
  }
28
57
  exports.toGlobalDataVersion = toGlobalDataVersion;
package/lib/index.d.ts CHANGED
@@ -4,7 +4,7 @@
4
4
  * This source code is licensed under the MIT license found in the
5
5
  * LICENSE file in the root directory of this source tree.
6
6
  */
7
- import { LoadContext, Plugin } from '@docusaurus/types';
8
- import { PluginOptions, LoadedContent } from './types';
9
- export default function pluginContentDocs(context: LoadContext, options: PluginOptions): Plugin<LoadedContent>;
7
+ import type { LoadContext, Plugin } from '@docusaurus/types';
8
+ import type { PluginOptions, LoadedContent } from '@docusaurus/plugin-content-docs';
9
+ export default function pluginContentDocs(context: LoadContext, options: PluginOptions): Promise<Plugin<LoadedContent>>;
10
10
  export { validateOptions } from './options';