https://github.com/younata/mdbook-section-validator

mdBook preprocessor for defining conditionally valid sections
https://github.com/younata/mdbook-section-validator

Last synced: 27 days ago
JSON representation

mdBook preprocessor for defining conditionally valid sections

• Host: GitHub
• URL: https://github.com/younata/mdbook-section-validator
• Owner: younata
• Created: 2021-05-21T04:23:30.000Z (over 3 years ago)
• Default Branch: main
• Last Pushed: 2021-06-15T02:29:22.000Z (over 3 years ago)
• Last Synced: 2024-09-19T01:49:05.410Z (about 2 months ago)
• Language: Rust
• Size: 28.3 KB
• Stars: 1
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

• awesome-starred - younata/mdbook-section-validator - mdBook preprocessor for defining conditionally valid sections (others)

README

        
# mdbook-section-validator

## Getting Started

First, install the `mdbook-section-validator` crate

```

cargo install mdbook-section-validator

```

Then, add the following line to your `book.toml` file

```toml

[preprocessor.section-validator]

```

Finally, add some custom CSS styling to control how the section validation sections work, I use the following in [personal-knowledge](https://github.com/younata/personal_knowledge/blob/master/css/custom.css):

```css

.validated-content {

    background-color: var(--quote-bg);

    border: 1px solid var(--quote-border);

    padding: 0 16px;

}

```

Once done, you can now use `!!!` at the beginning of lines to define sections to include only if the issues linked are still valid.

After the `!!!` starting a conditional inclusion, you must include a comma-separated list of URLs to tickets.

If all the linked issues are still open, then the markdown in the section will be included. The section is either removed, or prepended with a note stating that the section is out of date. 

```

# Chapter 1

!!!https://github.com/younata/mdbook-section-validator/issues/1,https://github.com/younata/mdbook-section-validator/issues/2

This is only rendered while issues 1 and 2 of younata/mdbook-section-validator are open. If 1 is closed, but not 2, then this is removed the next time mdbook renders. 

!!!

This is always rendered.

```

The inner contents will be rendered as markdown when running `mdbook build` or `mdbook serve` as usual.

## Configuration

As noted, this defaults to removing sections that are no longer valid. You can configure that be overriding `hide_invalid` to false.

You can configure the message to be shown by setting `invalid_message` to any string. It will be rendered as markdown.

```toml

[preprocessor.section-validator]

hide_invalid = false

invalid_message = "Warning, this content is out of date and is included for historical reasons."

```