H1 tags link in document navigation - Githubissues

eosnetworkfoundation / docsgen

Scripts for creating docs.eosnetwork.com pulls from various eos nf repos and builds static HTML to power website

Other

3 stars 0 forks source link

H1 tags link in document navigation #37

Closed lparisc closed 1 year ago

lparisc commented 2 years ago

Seems like anchor tags are not generated for heading level 1 (#) in rendered markdown files. This also affects page navigation since first section titles/links are missing. Not sure whether filing this as a bug, enhancement, or neither. Seems like docusaurus is adhering to the unofficial rule that 1st headings are used for page title, while 2nd/3rd+ headings used for actual section titles. If we also adhere to this, then we need to update all docs and convert # —> ##, ## —> ###, etc. Thoughts? @ericpassmore

ericpassmore commented 2 years ago

Lots in this comment, can we pull this apart

page titles - Set by H1 or overridden by YAML meta-data block at top of page
anchor tags - Navigating to H1 and navigation to page would seem to me to be the same. This is because H1 is at the top of the page I'm having trouble figuring out how this helps.
section titles - are these ok or need updates

Any way we can separate out these issues

ericpassmore commented 2 years ago

See below, the anchor is ignored but looks like it works. From my POV this is a not broken/ won't fix. Good to have some specific examples to better understand the issue

Screen Shot 2022-09-07 at 12 24 34 PM

ericpassmore commented 2 years ago

telegram-cloud-photo-size-1-4958810786189388253-y

lparisc commented 2 years ago

^^^ That's what docusaurus should display. source: https://raw.githubusercontent.com/eosnetworkfoundation/welcome/main/docs/04_protocol/01_consensus_protocol.md current view (as of 9/8/22): http://docs.eosnetwork.com/welcome/latest/protocol/consensus_protocol

ericpassmore commented 2 years ago

config failed [INFO] [en] Creating an optimized production build... [ERROR] Unable to build website for locale en. [ERROR] ValidationError: "tableOfContents.minHeadingLevel" must be greater than or equal to 2 [INFO] Docusaurus version: 2.1.0

ericpassmore commented 2 years ago

File with test is in Docusaurus packages/docusaurus-theme-classic/src/tests/options.test.ts

lparisc commented 1 year ago

This was a won't fix because we opted to avoid using the first heading (#) altogether in the affected markdowns, in favor of the title metadata, and promote all headings one level up, so all sections start at least from the second heading (##) up.