Docs: 404 page update #465
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
mmcallister
added
documentation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
Closes gravitational/teleport#15061 We want to encourage a more textual approach to the docs. Add this as a general goal to the style guide. If ther eare specific violations of this style suggestion that we want to address with documentation efforts, linters, etc., we can plan these separately.
* added javascript to handle version links * lint fix --------- Co-authored-by: Steven Martin <[email protected]>
- Update config.json - Add a submodule for v17 - Update .gitmodules
This reverts commit fa4bfff.
Bumps [braces](https://github.com/micromatch/braces) from 3.0.2 to 3.0.3. - [Changelog](https://github.com/micromatch/braces/blob/master/CHANGELOG.md) - [Commits](micromatch/braces@3.0.2...3.0.3) --- updated-dependencies: - dependency-name: braces dependency-type: indirect ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Add a `config.json` field within each `navigation` entry called `generateFrom`. This designates a relative path from `docs/pages` from which to generate entries within the sidebar. When generating pages, a function called `generateNavPaths` looks for pages to use as second-level section introductions. As with the Docusaurus convention, second-level section introductions have the same name as their parent directory. Adding a `generateFrom` field is consistent with the Docusaurus approach to sidebar generation, in which a configuration field indicates which directory to generate a section from. This gives us control over the title and icons we use for navigation sections, which aren't available to fetch from a directory tree alone. It also lets us use the current, hardcoded `entries` approach for some sections if we need to. Also un-skips some accidentally skipped tests.
Improve the sidebar generator to accommodate the reorganized docs site. - Alphabetize auto-generated sidebar entries. The exception is any page that includes "Introduction" or "introduction" in the title. Elevate these to the first entry to avoid a confusing sidebar order. - Show third-level category pages in the sidebar without showing their contents. This way, we can add content one level beyond the level permitted in the sidebar while still showing the category page for that content in the sidebar. - Allow for a category page to be at the same level as its associated subdirectory. This is to accommodate the Terraform Provider reference which, because of the way it's generated, can only include a category page outside of its associated subdirectory. This does not abide by the Docusaurus convention, so we will need to figure out a solution eventually, but this is a quick alternative to tide us over. - Only add ".mdx" files to the sidebar. Otherwise, the generator attempts to add vim swapfiles etc.
As we reorganize the documentation, it becomes cumbersome to manually change lists of links to pages within the documentation, e.g., in table of contents pages for subsections of the docs. This change adds a remark plugin for generating a list of links to pages in the current directory. The plugin works similarly to `remark-includes`, and accesses the local filesystem during the docs build. It replaces any lines consisting of `(!toc!)` with a list of links to pages in the current directory. The assumption is that a category page within a directory can use this to list contents.
Updating description requirements
Currently, the code that generates the navigation sidebar from a directory tree stops at the second level of a given top-level section. However, some sections include three levels of content. This change edits the sidebar generator so it works recursively. Also fix an issue with the `DocsNavigationItems` component that prevents the docs site from highlighting sidebar entries past two levels of depth. The component treats a sidebar subsection as "active" if one of its entries is equivalent to the current page path. But if the current page path is a grandchild of a sidebar subsection, this means that the component hides the grandchild, since none of the children of the subsection is equivalent to the current page. This change determines that a sidebar subsection is "active" if the selected path _starts with_ the subsection path. Also edit the CSS padding of navigation links to depend on the current level of the navigation menu. This allows for indentation of submenu links beyond the second level.
|
This looks like a bunch of extra commits got dragged in on accident. Could you take a look? |
benarent
reviewed
Oct 22, 2024
|
@travelton when you have bandwidth can you have a look too? The commits look relevant and the conflicts minor, as this issue has been open for awhile. |
|
I think a bunch of extra commits got dragged into this one on accident. can you rebase on main and squash the 404 changes and see if that fixes it? thanks |
|
Not sure what happened here. Rather than rebasing and force pushing, let's abandon this PR and start with a clean slate. See #501 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is for issue gravitational/docs-website#67
The 404 page in Docs needs some work.
Docs
https://goteleport.com/docs/blah/
vs
Website
https://goteleport.com/blah/