Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make sub-sections linkable #316

Open
awesomeAD1 opened this issue May 3, 2021 · 5 comments
Open

Make sub-sections linkable #316

awesomeAD1 opened this issue May 3, 2021 · 5 comments

Comments

@awesomeAD1
Copy link
Contributor

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.

@kazk
Copy link
Member

kazk commented May 3, 2021

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.

@hobovsky
Copy link
Contributor

hobovsky commented May 3, 2021

Should I think about preparing some summaries for subsections which are missing them now, then?

@kazk
Copy link
Member

kazk commented May 3, 2021

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.

@awesomeAD1
Copy link
Contributor Author

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?

@kazk
Copy link
Member

kazk commented May 3, 2021

No changes to the sidebar. It's a new page under Recipes.

- Authoring
  - Recipes
    - Overview

When visiting /authoring/recipes/, Authoring > Recipes will be expanded.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants