bevyengine / bevyengine/bevy-website

Better docs root section algorithm

Open
#1,181 0 comments 0 reactions 0 assignees View on GitHub
A-Book A-Migration Guides A-Quick-Start C-Code Quality C-Feature C-Webdev S-Needs-Design
Dominant language
JavaScript
Stars
249
Forks
450
Avg merge
16h 20m
Merged PRs (30d)
6

Description

As it stands, the original "algorithm" was to just get the second section in the path and presuming that should be the root section of the docs page or section e.g. `/learn/book` or `/learn/quick-start`. However, now that we having the `/contributing` sections this logic has been dethroned and the immediate, albeit hacky solution, is #1179 where we hard code the root section paths.

A better — but failed — procedural solution that has been thought up is to mark the root section with a Zola frontmatter toml variable:
1. Get the default root section path (presumed current section, or if it is a page then the section that holds the current page).
1a. If potential root section isn't marked root then get the next root section above / the section holding this section.
1b. Repeat 1a until root section is found.
2. If there is no root section then leave the root section variable empty and let Zola crash.

The reason this solution hasn't been implemented is because it seems to need a while loop which is not a part of the Tera templating language. So it can not be used. As such an actual working design needs to be made.

Contributor guide

Open the contributing guide

Research direction

The issue names no files or tests; begin by reviewing the hard-coded root-section workaround in #1179 and the Zola/Tera templating constraints described here. Define and validate a working algorithm for /learn, /contributing, nested sections, and pages, with a clear fallback when no root section is found.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, web-dev
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.