Giters

dauxio / daux.io

Daux.io is an documentation generator that uses a simple folder structure and Markdown files to create custom documentation on the fly. It helps you create great looking documentation in a developer friendly way.

Home Page:https://daux.io/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Ids for local anchors in headlines differ to them on Github

axelhahn opened this issue · comments

commented

(Maybe it is a feature request - not a bug)

Describe the bug
Local anchors of md files in a docs folder have another id in the rendered view on Github or Gitlab - compared to the local anchors in the daux rendered page.

To Reproduce
Steps to reproduce the behavior:

  1. Got to https://daux.io/Getting_Started.html ... in the TOC have look to the target in the link "Features" (it is "#page_features")
  2. Go to the corresponding md file https://github.com/dauxio/daux.io/blob/master/docs/00_Getting_Started.md ... the headline "Fetaures" has the id "#features" (without prefix "page_")

Expected behavior
If I publish my code and md files in docs folder on Github and want to use local anchors in the markdown then I must decide: shall they work for Github rendering or for the generated pages with Daux.

[my local link](#somewhere) vs. [my local link](#page_somewhere)

It would be good if Daux would create the ids of headlines in the same way like Github does:

  • without "page_" prefix
  • do not convert spaces on headline to "_" but to "-" (see Headline "For developers" on Getting started page ... Github uses "#for-authors" vs Daux "#page_for_authors")
  • (handling of special chars in headlines and its conversion in the ids I didn't check)

Screenshots
none

Desktop (please complete the following information):
Linux; PHP 8.0.14; Daux 0.17.2

Smartphone (please complete the following information):
none

Additional context
none

commented

I'll see if that's possible, we should be able to get close to that.

By any chance do you know if GitHub has a documentation on the rules used to change titles to ids ?

commented

I am not a markdown guru ... what I found:

Github has a documentation:
https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
... but I didn't see something about generation of the ids.

Gitlab tells a bit more: https://docs.gitlab.com/ee/user/markdown.html#header-ids-and-links
The IDs are generated from the content of the header according to the following rules:

  • All text is converted to lowercase.
  • All non-word text (such as punctuation or HTML) is removed.
  • All spaces are converted to hyphens.
  • Two or more hyphens in a row are converted to one.
  • If a header with the same ID has already been generated, a unique incrementing number is appended, starting at 1.
commented

Thanks for the links, I changed the permalinks and they should be compatible with GitHub and GitLab for most cases.

The changes are in the master branch and should be released in the next few days

commented

Released in version 0.18.0