Auto-generate article links from the navigation Key #84

Open
opened 2 years ago by lhinderberger · 1 comments
Collaborator

Currently, links to other articles in the documentation are set manually, like this:

[Article Name](/path/to/article)

...which is a nice and simple approach, but it has turned out to be somewhat error-prone. Weaknesses of this approach include:

  • As our article root is /content, contributors might prepend that to links, leading to dead links, if unnoticed
  • Prone to typos
  • Article Name is redundant and thus hard to update

I suggest we instead build links by auto-generating them from their unique navigation Key, which each article already has:

The article [](article:FirstRepository) defines this in greater detail

or, to explicitly define a title

If you want to know how to create your first repository, read [the corresponding article](article:FirstRepository)

If a key is given that could not be found, site generation would yield an error, thus, hopefully no more dead links (within Documentation at least).

To implement this, we'd need to find out how to customize hyperlink generation in Eleventy, which might be hard but worth it in the end.

Currently, links to other articles in the documentation are set manually, like this: ``` [Article Name](/path/to/article) ``` ...which is a nice and simple approach, but it has turned out to be somewhat error-prone. Weaknesses of this approach include: - As our article root is `/content`, contributors might prepend that to links, leading to dead links, if unnoticed - Prone to typos - Article Name is redundant and thus hard to update I suggest we instead build links by auto-generating them from their unique navigation Key, which each article already has: ``` The article [](article:FirstRepository) defines this in greater detail or, to explicitly define a title If you want to know how to create your first repository, read [the corresponding article](article:FirstRepository) ``` If a key is given that could not be found, site generation would yield an error, thus, hopefully no more dead links (within Documentation at least). To implement this, we'd need to find out how to customize hyperlink generation in Eleventy, which might be hard but worth it in the end.
lhinderberger added the
Status: Needs feedback
Kind: Enhancement
labels 2 years ago

I'm all for it. This somewhat like how asciidoctor works.

I have to say that right now, unfamiliar users that find themselves on
https://codeberg.org/Codeberg/Documentation/src/branch/master/content/getting-started/index.md

would try to click the links

"finding out more about Codeberg" and "your first steps on Codeberg"

and it will give out 404

It would be better if those were unclickable.

I'm all for it. This somewhat like how asciidoctor works. I have to say that right now, unfamiliar users that find themselves on https://codeberg.org/Codeberg/Documentation/src/branch/master/content/getting-started/index.md would try to click the links "finding out more about Codeberg" and "your first steps on Codeberg" and it will give out 404 It would be better if those were unclickable.
lhinderberger added the
Part: Generator
label 10 months ago
Sign in to join this conversation.
No Milestone
No Assignees
2 Participants
Notifications
Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Codeberg/Documentation#84
Loading…
There is no content yet.