Documentation Guides

Links #

Links allow you to reference other pages, external websites, or specific sections within your documentation.

Inline links are the standard Markdown syntax for creating clickable text:

[Link text](URL)

Examples #

Link to an external website:

[Rust documentation](https://doc.rust-lang.org/)

Result: Rust documentation

Link to another page in your documentation:

[See the markdown guide](../markdown.html)

Result: See the markdown guide

Link to a specific section using anchors:

[Jump to reference links](#reference-style-links)

Result: Jump to reference links

You can add a title attribute that appears on hover:

[Romero](https://git.sr.ht/~ne02ptzero/romero "The romero documentation generator")

Result: Romero

For better readability in source files, you can define links separately:

This is [an example][example] reference-style link.

[example]: https://example.com "Optional Title"

Result: This is an example reference-style link.

You can also use the link text as the reference:

Visit the [Rust website][] for more information.

[Rust website]: https://www.rust-lang.org/

Result: Visit the Rust website for more information.

URLs and email addresses can be automatically converted to links by wrapping them in angle brackets:

<https://example.com>
<user@example.com>

Result:

When linking to other pages within your documentation, use relative paths.

Automatic .md to .html Translation #

Romero automatically translates .md links to .html links in the rendered output. This means you can write links using the source file extensions:

[Content Structure](../contentstructure.md)
[Images](images.md)
[Getting Started](../../gs/README.md)

These will be automatically converted to .html in the output:

Using .md extensions in your source files is preferred because:

  1. Editor navigation: Most editors and IDEs can follow .md links directly, allowing you to navigate between documentation pages while writing.

  2. GitHub/GitLab preview: When viewing your documentation source on code hosting platforms, .md links work correctly in the rendered preview.

  3. Consistency: Your links match the actual source file names, making it easier to verify paths are correct.

  4. Portability: If you ever need to use the raw markdown files outside of romero, the links will still work.

You can still use .html extensions if you prefer—they will work correctly in the rendered output. However, those links won’t be navigable in your editor or on source hosting platforms.