feat(v2): auto-generated sidebars, frontmatter-less sites by slorber · Pull Request #4582 · facebook/docusaurus

slorber · 2021-04-06T18:09:46Z

Motivation

Fixes #3464

Good description of this PR here: #3464 (comment)

Make it easy to create a site without any sidebar, and infer the sidebar from the FS structure
Make it easy to have no frontmatter at all, and derive good metadata from FS naming conventions (file number prefixes)

Breaking changes:

A site without sidebars file will now autogenerate a sidebar automatically from the docs folder. Use an empty sidebars file if you want no sidebar at all.
By default, we strip numbers in front of folders/filenames, as numbers prefixes are often used to provide docs order: this could have unintended side-effects if you have existing docs starting with numbers.

Have you read the Contributing Guidelines on pull requests?

yes

Test Plan

tests, preview, dogfooding

netlify · 2021-04-06T18:15:33Z

[V1]

Built with commit f23e823

https://deploy-preview-4582--docusaurus-1.netlify.app

github-actions · 2021-04-06T18:20:35Z

Size Change: +33 B (0%)

Total Size: 598 kB

Filename	Size	Change
`website/build/assets/js/main.********.js`	422 kB	+33 B (0%)

ℹ️ View Unchanged

Filename	Size	Change
`website/build/assets/css/styles.********.css`	87.2 kB	0 B
`website/build/blog/2017/12/14/introducing-docusaurus/index.html`	62.1 kB	0 B
`website/build/docs/introduction/index.html`	235 B	0 B
`website/build/index.html`	26.9 kB	0 B

_{compressed-size-action}

netlify · 2021-04-06T18:20:37Z

[V2]

Built with commit f23e823

https://deploy-preview-4582--docusaurus-2.netlify.app

github-actions · 2021-04-07T10:02:53Z

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟠 Performance	85
🟢 Accessibility	96
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

Lighthouse ran on https://deploy-preview-4582--docusaurus-2.netlify.app/

This reverts commit c81da98

…rumb + slugs

… sidebar generation code

# Conflicts: # packages/docusaurus-plugin-content-docs/src/docs.ts

…bars page doc

ywjr · 2021-04-30T00:59:47Z

Generating sidebar automatically is a good function. I suggest that when generating sidebar automatically, the system can add filtering rules to filter out some files (such as readme. md

borekb · 2021-05-12T11:01:38Z

By default, we strip numbers in front of folders/filenames, as numbers prefixes are often used to provide docs order: this could have unintended side-effects if you have existing docs starting with numbers.

(emphasis mine) @slorber That is very true for us 😄. We have a numbered tutorial like this:

01-intro
02-build-ui
03-fetch-data
etc.

The files keep working as 01-intro.md but URLs are suddenly without these numbers, leading to 404s 🙁.

Any way to work around this?

slorber · 2021-05-12T12:38:17Z

@borekb not sure to understand why you want the numbers in the URLs?

In any case, you should be able to use a custom slug to add these numbers back, or simply disable the feature with numberPrefixParser: false in the docs plugin/preset config

borekb · 2021-05-12T12:40:52Z

It's just how it was, the tutorial part of our docs site used numbers in the URLs. Thanks for the tip with numberPrefixParser!

0Grit · 2021-11-11T12:55:29Z

packages/docusaurus-plugin-content-docs/src/sidebarItemsGenerator.ts

+  position?: number;
+  collapsed?: boolean;
+
+  // TODO should we allow "items" here? how would this work? would an "autogenerated" type be allowed?


@slorber Assuming based on this that I won't be able to do what I asked about in an earlier comment?
#3464 (comment)

No I don't think it's possible atm but we may add support for it if there's a good use-case exposed clearly, preferably with a concrete example showcasing the problem (seeing sources is better)

POC of autogenerated sidebars

46fb9ca

slorber added the pr: new feature This PR adds a new API or behavior. label Apr 6, 2021

facebook-github-bot added the CLA Signed Signed Facebook CLA label Apr 6, 2021

use combine-promises utility lib

749a251

slorber added 2 commits April 7, 2021 18:50

autogenerated sidebar poc working

c81da98

Revert "autogenerated sidebar poc working"

b39231f

This reverts commit c81da98

slorber added the pr: breaking change Existing sites may not build successfully in the new version. Description contains more details. label Apr 7, 2021

slorber mentioned this pull request Apr 7, 2021

[v2.alpha.62] sidebars.json is required after upgrading from alpha.61 to alpha.62 #3366

Closed

slorber added 7 commits April 7, 2021 19:09

POC of auto-generated sidebars for community docs

e4dd084

update tests

c285c65

add initial test suite for autogenerated sidebars + fix some edge cases

69da2a1

Improve autogen sidebars: strip more number prefixes in folder breadc…

9a6904b

…rumb + slugs

fix typo!

15e3f4b

Add tests for partially generated sidebars + fix edge cases + extract…

6034b64

… sidebar generation code

Ability to read category metadatas file from a file in the category

5224653

slorber changed the title ~~feat(v2): auto-generated sidebars~~ feat(v2): auto-generated sidebars, frontmatter-less sites Apr 9, 2021

slorber mentioned this pull request Apr 9, 2021

feat(v2): various markdown string parsing improvements/fixes #4590

Merged

slorber added 7 commits April 9, 2021 19:37

Merge branch 'master' into slorber/autogen-sidebars

3175db0

# Conflicts: # packages/docusaurus-plugin-content-docs/src/docs.ts

fix tests

1bd562b

change position of API

abf9b0b

ability to extract number prefix

3d55863

stable system to enable position frontmatter

d49d2e3

fix tests for autogen sidebar position

5a4487d

Merge branch 'master' into slorber/autogen-sidebars

69c83ea

slorber marked this pull request as ready for review April 13, 2021 10:45

slorber requested a review from lex111 as a code owner April 13, 2021 10:45

slorber added 12 commits April 13, 2021 19:23

test for custom sidebarItemsGenerator fn

cbfab8c

fix category metadata + add link to report tutorial issues

1ace81e

Merge branch 'master' into slorber/autogen-sidebars

3a27c3e

fix absolute path breaking tests

177a41a

fix absolute path breaking tests

35282fa

Add test for floating number sidebar_position

db806b1

add sidebarItemsGenerator unit tests

1a48e23

add processSidebars unit tests

c7d09e6

Fix init template broken links

9705029

windows test

2f5fdd4

increase code translations test timeout

727903d

cleanup mockCategoryMetadataFiles after windows test fixed

7ca2ff7

slorber mentioned this pull request Apr 14, 2021

chore(v2): fix yarn2 end2end test by using lerna publish --exact #4613

Merged

slorber added 4 commits April 14, 2021 17:26

Merge branch 'master' into slorber/autogen-sidebars

4662610

update init template positions

cee22a7

fix windows tests

5acb3d1

fix comment

827a4cb

slorber linked an issue Apr 14, 2021 that may be closed by this pull request

Allow configuring the title of a sidebar link in sidebar.js in plugin-docs #4314

Closed

slorber added 3 commits April 15, 2021 13:10

Add autogenerated sidebar items documentation + rewrite the full side…

e240448

…bars page doc

add useful comment

87102f6

fix code block title

f23e823

slorber merged commit db79d46 into master Apr 15, 2021

valentine mentioned this pull request Apr 17, 2021

[v2.0.0-alpha.73] autogenerated sidebars: have a stripNumberPrefixes option in config file? #4640

Closed

tgreyuk mentioned this pull request May 2, 2021

Feature: (docusaurus) autogenerated sidebars typedoc2md/typedoc-plugin-markdown#217

Merged

slorber deleted the slorber/autogen-sidebars branch August 17, 2021 17:50

0Grit reviewed Nov 11, 2021

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Comments

feat(v2): auto-generated sidebars, frontmatter-less sites#4582

feat(v2): auto-generated sidebars, frontmatter-less sites#4582
slorber merged 53 commits intomasterfrom
slorber/autogen-sidebars

slorber commented Apr 6, 2021 •

edited

Loading

Uh oh!

netlify bot commented Apr 6, 2021 •

edited

Loading

Uh oh!

github-actions bot commented Apr 6, 2021 •

edited

Loading

Uh oh!

netlify bot commented Apr 6, 2021 •

edited

Loading

Uh oh!

github-actions bot commented Apr 7, 2021 •

edited

Loading

Uh oh!

ywjr commented Apr 30, 2021

Uh oh!

borekb commented May 12, 2021

Uh oh!

slorber commented May 12, 2021

Uh oh!

borekb commented May 12, 2021

Uh oh!

0Grit Nov 11, 2021

Uh oh!

slorber Nov 12, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Comments

Conversation

slorber commented Apr 6, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Have you read the Contributing Guidelines on pull requests?

Test Plan

Uh oh!

netlify bot commented Apr 6, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Apr 6, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Apr 6, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Apr 7, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ywjr commented Apr 30, 2021

Uh oh!

borekb commented May 12, 2021

Uh oh!

slorber commented May 12, 2021

Uh oh!

borekb commented May 12, 2021

Uh oh!

0Grit Nov 11, 2021

Choose a reason for hiding this comment

Uh oh!

slorber Nov 12, 2021

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

slorber commented Apr 6, 2021 •

edited

Loading

netlify bot commented Apr 6, 2021 •

edited

Loading

github-actions bot commented Apr 6, 2021 •

edited

Loading

netlify bot commented Apr 6, 2021 •

edited

Loading

github-actions bot commented Apr 7, 2021 •

edited

Loading