docs
docs copied to clipboard
codewars
Make sub-sections linkable
First off, feel free to change the terribly worded title of this issue.
Currently, documentation sub-sections only exist as drop-downs in the sidebar. For inter-linking purposes between documents, it would be nice if one could link directly to a section, e.g. authoring/recipes. As you can see, it shows a 404 error because there is no content to display. Other sub-sections have an overview page that is reachable via the sub-section url itself, e.g. authoring/guidelines, which displays the first sub-page, namely the Overview.
For sections that do not have an explicit overview, perhaps the contents of that section could be automatically generated as a list of links. For example, visiting https://docs.codewars.com/authoring/recipes would then display something like:
That way, if I wanted to link to "Recipes" in general from another place within the docs, I wouldn't have to link to one of the specific subpages.
We should have an overview page that explains the purpose of the subsection, even if it's very short. If a subsection is not describable, then it's probably not worth having that subsection.
List of pages are already in the sidebar, and duplicating that also pollutes search.
Should I think about preparing some summaries for subsections which are missing them now, then?
Let's fix 404 with a stub for now because that will show the sidebar listing pages at least. When there's no suitable page to show first (e.g., group of independent pages on a topic), write something to describe the group instead. Don't just list links because we already have a sidebar for that, and it pollutes the search result.
As a technical aside: how will this affect navigation in the sidebar? Would clicking on a sub-section header open that section's overview page and if so, how would this affect the drop-down behaviour?
No changes to the sidebar. It's a new page under Recipes.
- Authoring
- Recipes
- Overview
When visiting /authoring/recipes/, Authoring > Recipes will be expanded.