rust-lang / rust-lang/mdBook

Need option to disable the default hidelines feature for rust

Open
#2,881 0 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

In https://opengl.zgtm.eu/chapter_3.html I have Rust code, that contains multiline strings, which themselves contain C code (OpenGL shader).

E.g.:

const VERTEX_SHADER_SOURCE: &CStr = c"
#version 410 core

in vec3 position;

void main() {
    gl_Position = vec4(position, 1.0f);
}
";

I want syntax coloring, so I declared the code as rust (```rust). However, as the embedded C code in the string contains lines beginning with #, I need a way to disable the default behaviour of mdBook to hide all lines that begin with a `#`.

Proposed Solution

I propose to add a new config option default-hidelines under output.html.code that is "true" by default, but can be set to "false" if one wishes to disable the default behaviour:

[output.html.code]
default-hidelines = false

I have written a PR that implements this solution in #2518 .

Notes

Since I use the {{#include ..}}-helper of mdBook to include the code from the actual source files, I cannot use the workaround of using a double ##, that was proposed in #2518.

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 PR #2518 and the handling of the [output.html.code] configuration described in the issue. Done means mdBook accepts default-hidelines = false while preserving the current default behavior when the option is omitted, and prevents leading # lines in included Rust code from being hidden.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Feature
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.