📖 Improve website navigation and TOC docs

jupyter-book / mystmd

Command line tools for working with MyST Markdown.

https://mystmd.org/guide

MIT License

191 stars 61 forks source link

📖 Improve website navigation and TOC docs #1446

Closed choldgraf closed 2 weeks ago

choldgraf commented 1 month ago

This tries to make our Table of Contents and Website Navigation documentation a little bit clearer and easier to find. Here are major changes:

Move Table of Contents into Authoring instead of Websites. This is because most of the content there is not unique to websites, since you structure multi-page documents with the Table of Contents for any kind of export.
Adds a Websites section on Site Navigation to make it clear where to find menu item configuration. It also adds a brief description of the layout of the page.
- Note: this will only apply to the default themes, if we create dedicated documentation for those themes, we can move this section there.

changeset-bot[bot] commented 1 month ago

⚠️ No Changeset found

Latest commit: f8a69049a13cdd6c974c9b21e46f96a6afbc3def

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

agoose77 commented 2 weeks ago

I made some changes:

Moved the Deployment page to the page that is loaded when the dropdown is clicked
Shortened the discussion about BASE_URL for GH Pages; we already talk about its purpose elsewhere, and it should automatically be handled by the myst init --gh-pages command.

@choldgraf are you happy with (2)?

agoose77 commented 2 weeks ago

If @choldgraf gives this the go ahead, I'm then going to merge; I think we can iterate from here, and I'm worried about things becoming stagnant as we have an ever-growing list of PRs! Thanks @lwasser for your reviews here too :)

choldgraf commented 2 weeks ago

+1 to @rowanc1's suggestion as well as to your changes @agoose77 . I'm happy w the PR as-is but if you wanna move the TOC section lower before merging that works for me