rust-lang / rust-lang/mdBook

Add a way to ignore the source link file present in the SUMMARY.md while including the link.

Open
#2,573 7 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C-enhancement
Dominant language
Rust
Stars
22.2k
Forks
1.9k
PR merge metrics
PR metrics pending

Description

Problem

I want to add an auto generated part of a documentation that I am writing but the tool I am using generates HTML so i want to have a link to the page generated by the tool in the sidebar. Problem the book won't build because the source doesn't exist.

Proposed Solutions

Solution 1: Add a syntax to the SUMMARY parser to make it so it will ignore the file behind the link but generate the the link .

Solution 2: If the link is not a md file it inserts the link into the sidebar without checking for a file in the source directory and leave it to the user to ensure the file at the link destination is present in the output directory.

Solution 3: Add a way to hook into the serve process to have a post build script run before the files are served where i can fix the generated part with a bash script.

Notes

Currently to include my generated part i put an empty index.md file where the index.html would end up in the finished build but the problem arise when running mdbook serve where the generated HTML is systematically replaced by the empty file.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing the SUMMARY parser and the mdbook serve process described in the issue, comparing how linked HTML and source files are handled. Review the three proposed approaches and define which behavior should be implemented; done means a generated HTML link appears in the sidebar without an empty source file replacing it during serve.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.