Is there a way to make the sidebar & outline management more DRY?

[brikis98]

I was working on a guide for the Production Framework, with the hope of having the sidebar on the left and an outline of the content in the first part of the article too, and as best as I can tell, this requires the following:

1. Create folders and files with specific naming conventions: 01-xxx/01-intro.md, 01-xxx/02-another-thing.md, 02-xxx/01-intro.md.
2. Manually create sidebars/production-framework-guide.js and copy/paste the file/folder structure into it, and manually keep it in sync as new files are added/removed.
3. Specify pagination_label in some of the .md files. Not sure what happens if I don't?
4. Manually include the page title as an h1 via # <title> and in the front matter.
5. If I want an outline in addition to the sidebar, I have to create the outline manually in the body of the intro .md file. I didn't see a way to generate this programmatically?

Note that I'm not sure I'm doing this right; I was basically copying the Ref Arch guide structure and used a lot of trial and error to get this working. So if there's a simpler way, LMK!

Is there any way to just create the files on disk and have (a) the sidebar created automatically and (b) a programmatic way to have an outline in the body too?

[eak12913]

Is there any way to just create the files on disk and have (a) the sidebar created automatically

Yes - Docusaurus has built-in solution for this. There are a few limitations:

• The ordering is alphabetical and if you want to change that, you have to do that in individual files in their fronmatter via the sidebar_position property.
• There's no underlying control about how the intermediate folder names get capitalized. For example if I was autogenerating a sidebar and there was a /foo/bar/baz.md - I might want the sidebar to display: "Foo -> Bar -> Baz"...and instead - I'd get "foo -> bar -> Baz" (because baz.md has either a frontmatter in there or has a top level H1 that sets the title. To get around this - you can insert a category.json file

(b) a programmatic way to have an outline in the body too?

The outline should appear on the left side and should scroll with the content. Is that not happening for your docs? You can configure how many levels are captured by the outline. The docs are here. I'm not sure if you specifically want the outline to appear in the body of the .md document itself. If so - what's the use case?

Create folders and files with specific naming conventions: 01-xxx/01-intro.md, 01-xxx/02-another-thing.md, 02-xxx/01-intro.md.

We were struggling with naming conventions and were trying to balance viewing in GitHub, on your dev machine and on doc.gruntwork.io. We thought that prefacing with 01-..., 02-.... was a good solution to this. The solution did give the best consistency in viewing between all the various environments but it was a nightmare to perform any kind of refactoring. Want to add a new section? You now have to rename lots of files and update lots of links in all sorts of places. In light of the huge cost of making any kind of changes we opted to do away with the numeric prefixes. That work is all in #132

I also have a local tool that I can use to help you generate a sidebar.js from your folder structure and output it as something that can be pasted directly into a js file. This tool is not fully baked - but I can help you out if you want to generate a sidebar quickly. We're also tracking finalizing the tool in JIRA

Specify pagination_label in some of the .md files. Not sure what happens if I don't?

You don't have to do this unless you want to specifically override what shows up in the "back" and "next" buttons that appear at the bottom of your articles. If you don't override then it will use the first h1 of the previous and next pages in the hierarchy. If those pages set a pagination_label then it will show that value instead.

Manually include the page title as an h1 via # <title> and in the front matter.

You don't have to specify anything in the frontmatter unless your <title> should be different from what gets displayed in the sidebar

[ebeneliason]

(b) a programmatic way to have an outline in the body too?

The outline should appear on the left side and should scroll with the content. Is that not happening for your docs? You can configure how many levels are captured by the outline. The docs are here. I'm not sure if you specifically want the outline to appear in the body of the .md document itself. If so - what's the use case?

Minor correction — the outline (technically, TOC) — appears to the right of the page content. It should appear automatically. It can be embedded in the body of the document, but I'm not sure when there would be a need. You can also configure the depth using front matter, but by default it shows H2 + H3 (Docusaurus assumes the only H1 on the page is the title.)

I also have a local tool that I can use to help you generate a sidebar.js from your folder structure and output it as something that can be pasted directly into a js file. This tool is not fully baked - but I can help you out if you want to generate a sidebar quickly. We're also tracking finalizing the tool in JIRA.

To be clear, we've explicitly decided to standardize on the sidebar.js pattern over auto-generation for most content due to the declarative nature and flexibility it offers. There are tradeoffs, as always, but we think it's the best choice overall.

[brikis98]

Thank you both, that's very helpful. I was able to make things a bit more DRY following Eugene's advice. See #145.

Note that, IMO, there are reasons to put an outline right in the body of the doc: namely, in an introductory section that says, "here's the outline of what we'll be discussing today." See https://deploy-preview-145--pensive-meitner-faaeee.netlify.app/docs/guides/production-framework#lets-get-started for an example.

[brikis98]

Also, I think this issue can be closed.