rust-lang / rust-lang/mdBook

Easily include a file setting the syntax highlighting and also showing the name of the file

Open
#2,663 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C-enhancement
Dominant language
Rust
Stars
22.2k
Forks
1.9k
Avg merge
2d 21h
Merged PRs (30d)
12

Description

Problem

Right now if I would like to include a source file I need to use something like this: {{#include file.rs}} I also need to wrap it with

```rust
```

I would also like to add the name of the file above the included file
And maybe even make it a link to the file in my github repository.

Proposed Solution

It would be nice to be able to write something like:

{% include file.rs %}

That would be expanded to something like this:

    ```rust
    [**examples/intro/hello/src/main.rs**](https://github.com/szabgab/rust.code-maven.com/blob/main/slides/rust/examples/intro/hello/src/main.rs)
    {{#include examples/intro/hello/src/main.rs }}
    ```

The programming language would be deducted from the file-extension.

It would be nice if mdbook had all kinds of extension like this using the liquid-like format, but for quicker solution it might be a preprocessors. Maybe it could be added to embedify.
What do you think @Mr-Addict ?

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 reviewing mdBook's existing {{#include ...}} behavior and the preprocessor approach described in the issue. Compare the proposed {% include ... %} syntax, automatic language detection, filename display, and optional GitHub link, then define a focused scope and acceptance criteria before implementation.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.