Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

{{#include ...}} with indented #1564

Open
kynthus opened this issue Jun 5, 2021 · 0 comments · May be fixed by #1565
Open

{{#include ...}} with indented #1564

kynthus opened this issue Jun 5, 2021 · 0 comments · May be fixed by #1565
Labels
A-link-preprocessor Area: Link preprocessor, #{{include}}, etc.

Comments

@kynthus
Copy link

kynthus commented Jun 5, 2021

First, this ticket isn't a bug, it's more like a feature request.

{{#include ...}} currently does not consider indentation when replaced.
For example, replace some code of a control flow, struct, enum, and implementation from another file, and dealing with a code block that is indented with bullets or sequences, the second and subsequent lines are not indented.
As a result, the HTML layout and code indentation may be corrupted.

Example code

# sample.md

- Example without including files.  

  ```rust
  struct MyStruct;

  impl MyStruct {
      pub fn myfn() -> () {
          println!("MyStruct#myfn()");
      }
  }

  pub fn main() -> () {
      println!("main()");
  }
  ```

- Example using including files.  

  ```rust
  struct MyStruct;

  impl MyStruct {
      {{#include myfn.rs}}
  }

  {{#include main.rs}}
  ```
// myfn.rs
pub fn myfn() -> () {
    println!("MyStruct#myfn()");
}
// main.rs
pub fn main() -> () {
    println!("main()");
}

Personally, I expected that both cases with and without {{#include}} would be output with the same layout.
However, the inclusion of myfn.rs and main.rs does not indent the second and subsequent lines, so the results are different as shown below.

Output HTML

  • Without including files.

    <p>Example without including files.</p>
    <pre><pre class="playground"><code class="language-rust">struct MyStruct;
    
    impl MyStruct {
        pub fn myfn() -&gt; () {
            println!(&quot;MyStruct#myfn()&quot;);
        }
    }
    
    pub fn main() -&gt; () {
        println!(&quot;main()&quot;);
    }
    </code></pre></pre>
  • Using including files.

    <p>Example using including files.</p>
    <pre><pre class="playground"><code class="language-rust">
    <span class="boring">#![allow(unused)]
    </span><span class="boring">fn main() {
    </span>struct MyStruct;
    
    impl MyStruct {
        pub fn myfn() -&gt; () {
      println!(&quot;MyStruct#myfn()&quot;);
    <span class="boring">}
    </span></code></pre></pre>
    </li>
    </ul>
    <p>}
    }</p>
    <p>pub fn main() -&gt; () {
    println!(&quot;main()&quot;);
    }</p>
    <pre><code></code></pre>

    image

I will submit a Draft PR that allows to output the same results.

@kynthus kynthus linked a pull request Jun 5, 2021 that will close this issue
kynthus added a commit to kynthus/mdBook that referenced this issue Jun 8, 2021
@ehuss ehuss added the A-link-preprocessor Area: Link preprocessor, #{{include}}, etc. label Jul 6, 2021
markmandel added a commit to markmandel/quilkin that referenced this issue Sep 14, 2021
Updates the custom filter documentation to the latest API changes.

This also includes using mdbook's `include` preprocessor to inject the
example code into the documentation.

Note: Because of the use of `include` preprocessor I had to remove the
Markdown lists, as they wouldn't format correctly
(See: rust-lang/mdBook#1564).

Closes googleforgames#373
markmandel added a commit to googleforgames/quilkin that referenced this issue Sep 16, 2021
* Docs: Updated Custom Filters

Updates the custom filter documentation to the latest API changes.

This also includes using mdbook's `include` preprocessor to inject the
example code into the documentation.

Note: Because of the use of `include` preprocessor I had to remove the
Markdown lists, as they wouldn't format correctly
(See: rust-lang/mdBook#1564).

Closes #373

* Fix CI build
* Review Updates.
kynthus added a commit to kynthus/mdBook that referenced this issue Oct 23, 2021
mgeisler added a commit to google/comprehensive-rust that referenced this issue Dec 1, 2023
I swear I tested this in an actual Rust file, but I somehow messed up
when copy-pasting it into the example. The code is now in the test
file so it will be correct.

Why is the indentation wrong? Because of

  rust-lang/mdBook#1564

The indentation is not kept by the included content, which breaks the
Markdown.
mgeisler added a commit to google/comprehensive-rust that referenced this issue Dec 1, 2023
I swear I tested this in an actual Rust file, but I somehow messed up
when copy-pasting it into the example. The code is now in the test file
so it will be correct.

Why is the indentation wrong? Because of

  rust-lang/mdBook#1564

The indentation is not kept by the included content, which breaks the
Markdown.
daviddrysdale added a commit to daviddrysdale/mdBook that referenced this issue Mar 1, 2024
Syntax is the same as {{#include}} except with a shift value and colon
before the remaining arguments, e.g.

  {{#include -2:somefile.rs:myanchor}}

A positive value for the shift prepends spaces to each line.

A negative value for the shift removes chars from the beginning of each
line (including non-whitespace chars, although this will emit an error
log).

Possibly helpful/relevant to:
- rust-lang#1564: #include with indented
- rust-lang#1601: option to remove indentation of included file snippets
daviddrysdale added a commit to daviddrysdale/mdBook that referenced this issue Mar 1, 2024
Syntax is the same as {{#include}} except with a shift value and colon
before the remaining arguments, e.g.

  {{#include -2:somefile.rs:myanchor}}

A positive value for the shift prepends spaces to each line.

A negative value for the shift removes chars from the beginning of each
line (including non-whitespace chars, although this will emit an error
log).

Possibly helpful/relevant to:
- rust-lang#1564: #include with indented
- rust-lang#1601: option to remove indentation of included file snippets
daviddrysdale added a commit to daviddrysdale/mdBook that referenced this issue Mar 2, 2024
Syntax is the same as {{#include}} except with a shift value and colon
before the remaining arguments, e.g.

  {{#include -2:somefile.rs:myanchor}}

A positive value for the shift prepends spaces to each line.

A negative value for the shift removes chars from the beginning of each
line (including non-whitespace chars, although this will emit an error
log).

Possibly helpful/relevant to:
- rust-lang#1564: #include with indented
- rust-lang#1601: option to remove indentation of included file snippets
daviddrysdale added a commit to daviddrysdale/mdBook that referenced this issue Mar 2, 2024
Syntax is the same as {{#include}} except with a shift value and colon
before the remaining arguments, e.g.

  {{#include -2:somefile.rs:myanchor}}

A positive value for the shift prepends spaces to each line.

A negative value for the shift removes chars from the beginning of each
line (including non-whitespace chars, although this will emit an error
log).

Possibly helpful/relevant to:
- rust-lang#1564: #include with indented
- rust-lang#1601: option to remove indentation of included file snippets
daviddrysdale added a commit to daviddrysdale/mdBook that referenced this issue Mar 2, 2024
Syntax is the same as {{#include}} except with a shift value and colon
before the remaining arguments, e.g.

  {{#include -2:somefile.rs:myanchor}}

A positive value for the shift prepends spaces to each line.

A negative value for the shift removes chars from the beginning of each
line (including non-whitespace chars, although this will emit an error
log).

Possibly helpful/relevant to:
- rust-lang#1564: #include with indented
- rust-lang#1601: option to remove indentation of included file snippets
daviddrysdale added a commit to daviddrysdale/mdBook that referenced this issue Mar 2, 2024
Syntax is the same as {{#include}} except with a shift value and colon
before the remaining arguments, e.g.

  {{#include -2:somefile.rs:myanchor}}

A positive value for the shift prepends spaces to each line.

A negative value for the shift removes chars from the beginning of each
line (including non-whitespace chars, although this will emit an error
log).

Possibly helpful/relevant to:
- rust-lang#1564: #include with indented
- rust-lang#1601: option to remove indentation of included file snippets
daviddrysdale added a commit to daviddrysdale/mdBook that referenced this issue Mar 2, 2024
Syntax is the same as {{#include}} except with a shift value and colon
before the remaining arguments, e.g.

  {{#include -2:somefile.rs:myanchor}}

A positive value for the shift prepends spaces to each line.

A negative value for the shift removes chars from the beginning of each
line (including non-whitespace chars, although this will emit an error
log).

Possibly helpful/relevant for:
- rust-lang#1564: #include with indented
- rust-lang#1601: option to remove indentation of included file snippets
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-link-preprocessor Area: Link preprocessor, #{{include}}, etc.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants