FuelLabs/fuels-rs

docs: improve upstream `md-book` code snippets display

Open

#388 opened on Jun 13, 2022

View on GitHub
 (0 comments) (1 reaction) (1 assignee)Rust (1,360 forks)batch import
blockedenhancementgood first issue

Repository metrics

Stars
 (43,211 stars)
PR merge metrics
 (No merged PRs in 30d)

Description

  • We now want all code that goes in the book to be tested (and put in the examples directory), so all code in The Book will soon be put there using the {{include path/to/file}} tag of md-book.

Problem: the formatting isn 't very nice, there's extra identation displayed because the code is inside a test function.

Fixing https://github.com/rust-lang/mdBook/issues/1601 would solve this! It would also be of benefit for all books!

Tagging @mitchmindtree for tooling consideration :smile:

Contributor guide

Research direction
Investigate the linked upstream issue (rust lang/mdBook#1601) to understand the proposed fix for code snippet indentation. Explore the `examples` directory in fuels rs and the mdBook configuration files (e.g., book.toml) to see how the include macro is currently used. Implement a workaround or contribute to the upstream fix to strip extra indentation from included code snippets. Check the assignee's comments for any prior work or direction.
Tech stack
rust
Domain
documentation
Issue type
Documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-2 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Blocked
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Mostly clear
Prerequisites
Rust basicsmdBookHTML/CSS fundamentals
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
40