feat(content-docs): version path & prefix configuration options #8737

Jersyfi · 2023-03-05T22:39:32Z

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

My personal motivation for modifying the docusaurus-plugin-content-docs plugin is to have more flexibility in the file structure. With this feature it is possible to group all files in one folder without having them in the project root folder.

Test Plan

I have added a test folder called versioned-site-with-custom-path with the versionPath and versionPrefix options set and all files grouped together. In this state the tests are simple and I need your opinion if any changes are needed.

Test links

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

Options

versionPath
type: string | undefined
default: undefined
versionPrefix
type: boolean
default: true

Mofified Documentation

Path: website/docs/api/plugins/plugin-content-docs.mdx
Deploy preview: https://deploy-preview-8737--docusaurus-2.netlify.app/docs/api/plugins/@docusaurus/plugin-content-docs/

Related issues/PRs

#8061

Added options to customize the path and the prefix of the versioned files

facebook-github-bot · 2023-03-05T22:39:37Z

Hi @Jersyfi!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at cla@meta.com. Thanks!

netlify · 2023-03-05T22:42:29Z

✅ [V2]

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`d8d5810`
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/64059a8602ce9a00087cc09e
😎 Deploy Preview	https://deploy-preview-8737--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 · 2023-03-05T22:42:59Z

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟢 90	🟢 97	🟢 100	🟢 100	🟢 90	Report
/docs/installation	🟠 70	🟢 100	🟢 100	🟢 100	🟢 90	Report

facebook-github-bot · 2023-03-06T00:33:21Z

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!

Jersyfi · 2023-03-06T07:45:23Z

website/docs/api/plugins/plugin-content-docs.mdx

@@ -34,6 +34,8 @@ Accepted fields:
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `path` | `string` | `'docs'` | Path to the docs content directory on the file system, relative to site directory. |
+| `versionPath` | `string` |  `''` | Path to versioned files on filesystem, relative to site dir. |


TODO

Found that i missed changing the versionPath default value from '' to undefined.

Jersyfi · 2023-03-06T11:16:37Z

packages/docusaurus-plugin-content-docs/src/versions/files.ts

    ? fileOrDir
    : `${pluginId}_${fileOrDir}`;
 }

-/** `[siteDir]/community_versioned_docs/version-1.0.0` */
+/** `[versionPath]/[pluginId?]_versioned_docs/version-1.0.0` */


Change the following comment word.
versionPath -> (versionSiteDir or versionDir)

Jersyfi · 2023-03-06T11:16:54Z

packages/docusaurus-plugin-content-docs/src/versions/files.ts

    `version-${versionName}`,
  );
 }

-/** `[siteDir]/community_versioned_sidebars/version-1.0.0-sidebars.json` */
+/** `[versionPath]/[pluginId?]_versioned_sidebars/version-1.0.0-sidebars.json` */


Change the following comment word.
versionPath -> (versionSiteDir or versionDir)

Jersyfi · 2023-03-06T11:18:17Z

packages/docusaurus-plugin-content-docs/src/versions/files.ts

-/** `community` => `[siteDir]/community_versions.json` */
-export function getVersionsFilePath(siteDir: string, pluginId: string): string {
-  return path.join(siteDir, addPluginIdPrefix(VERSIONS_JSON_FILE, pluginId));
+/** `community` => `[versionPath]/community_versions.json` */


Change the following comment word.
versionPath -> (versionSiteDir or versionDir)

slorber

Looks like a good first draft

That probably solves your use-case, but I think this API is a bit awkward and not the most flexible either.

Reading the docs, it's not so clear to me what versionPrefix even is 😅

I'd prefer if we worked on designing the API we want first before doing the implementation.

For now, I think this API is more flexible than yours and less confusing:

[
  "@docusaurus/plugin-content-docs",
  {
    id: "ios",
    path: "./ios-docs/v-next",
    versionPath: ({version}) => `./ios-docs/v-${version.toLowerCase().replace(".","-"}`,
  },
];

Note: we already have a version config map so we could also reuse it to allow configuring the fs path?

There's a bit of confusion between version route path and fs path unfortunately 🤪

See https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#ex-config

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        path: 'docs',
        versions: {
          current: {
            path: 'ios-2.0.0',
          },
          '1.0.0': {
            path: 'ios-1.0.0',
          },
        },
      },
    ],
  ],
};

We should discuss the tradeoffs of various design options we have (probably in the other issue so others can participate) and agree on something before implementing it.

Jersyfi · 2023-04-24T20:22:23Z

Closing the PR as there is no time for further changes.

Jersyfi added 3 commits March 5, 2023 13:59

Version Path & Prefix

8a5e81e

Added options to customize the path and the prefix of the versioned files

versionPath type & test changes

0559a6b

Removed unused test files & fixes

437334d

Jersyfi requested review from slorber, lex111 and Josh-Cena as code owners March 5, 2023 22:39

facebook-github-bot added the CLA Signed Signed Facebook CLA label Mar 6, 2023

Jersyfi commented Mar 6, 2023

View reviewed changes

Wrong default value for versionPath changed

d8d5810

Jersyfi commented Mar 6, 2023

View reviewed changes

Jersyfi changed the title ~~Version path & prefix configuration for plugin content docs~~ feat(content-docs): version path & prefix configuration options Mar 6, 2023

slorber requested changes Mar 9, 2023

View reviewed changes

slorber marked this pull request as draft March 9, 2023 18:22

Jersyfi mentioned this pull request Mar 10, 2023

Output directory of versioning - {PLUGIN_INSTANCE_ID}_versioned-docs should be configurable #8061

Open

2 tasks

Jersyfi closed this Apr 24, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(content-docs): version path & prefix configuration options #8737

feat(content-docs): version path & prefix configuration options #8737

Jersyfi commented Mar 5, 2023 •

edited

Loading

facebook-github-bot commented Mar 5, 2023

netlify bot commented Mar 5, 2023 •

edited

Loading

github-actions bot commented Mar 5, 2023 •

edited

Loading

facebook-github-bot commented Mar 6, 2023

Jersyfi Mar 6, 2023

Jersyfi Mar 6, 2023 •

edited

Loading

Jersyfi Mar 6, 2023 •

edited

Loading

Jersyfi Mar 6, 2023 •

edited

Loading

slorber left a comment •

edited

Loading

Jersyfi commented Apr 24, 2023

feat(content-docs): version path & prefix configuration options #8737

feat(content-docs): version path & prefix configuration options #8737

Conversation

Jersyfi commented Mar 5, 2023 • edited Loading

Pre-flight checklist

Motivation

Test Plan

Test links

Options

Mofified Documentation

Related issues/PRs

facebook-github-bot commented Mar 5, 2023

Action Required

Process

netlify bot commented Mar 5, 2023 • edited Loading

✅ [V2]

github-actions bot commented Mar 5, 2023 • edited Loading

⚡️ Lighthouse report for the deploy preview of this PR

facebook-github-bot commented Mar 6, 2023

Jersyfi Mar 6, 2023

Choose a reason for hiding this comment

TODO

Jersyfi Mar 6, 2023 • edited Loading

Choose a reason for hiding this comment

Jersyfi Mar 6, 2023 • edited Loading

Choose a reason for hiding this comment

Jersyfi Mar 6, 2023 • edited Loading

Choose a reason for hiding this comment

slorber left a comment • edited Loading

Choose a reason for hiding this comment

Jersyfi commented Apr 24, 2023

Jersyfi commented Mar 5, 2023 •

edited

Loading

netlify bot commented Mar 5, 2023 •

edited

Loading

github-actions bot commented Mar 5, 2023 •

edited

Loading

Jersyfi Mar 6, 2023 •

edited

Loading

Jersyfi Mar 6, 2023 •

edited

Loading

Jersyfi Mar 6, 2023 •

edited

Loading

slorber left a comment •

edited

Loading