mdbook-autosummary

KO | EN

gitlite — search

#javascript #python #hacktoberfest #typescript #golang #machine-learning #docker #macos #java #awesome #kubernetes #awesome-list #pytorch #open-source

mdbook-autosummary

(★ 11)

Generate SUMMARY.md files based on your book's file structure

mdbook-autosummary 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# mdbook-autosummary

Generate a `SUMMARY.md` for your [mdBook](https://github.com/rust-lang/mdBook) based on your folder structure!

> [!WARNING]
> The implementation is hacky and has several limitations, see [below](#limitations) for more info.

## Example

```
src
├── bar
│   ├── chapter_5.md
│   ├── chapter_6.md
│   └── index.md
├── chapter_1.md
├── chapter_2.md
├── foo
│   ├── baz
│   │   ├── chapter_7.md
│   │   └── index.md
│   ├── chapter_3.md
│   ├── chapter_4.md
│   └── index.md
├── index.md
└── SUMMARY.md
```

is turned into

```markdown

[Home](index.md)
[Chapter 1](chapter_1.md)
[Chapter 2](chapter_2.md)
- [Section Bar](bar/index.md)
  - [Chapter 5](bar/chapter_5.md)
  - [Chapter 6](bar/chapter_6.md)
- [Section Foo](foo/index.md)
  - [Chapter 3](foo/chapter_3.md)
  - [Chapter 4](foo/chapter_4.md)
  - [Section Baz](foo/baz/index.md)
    - [Chapter 7](foo/baz/chapter_7.md)

```

## Installation

### Binaries

The binaries are available in the [GitHub releases section](https://github.com/hypergonial/mdbook-autosummary/releases) for all major platforms.

### From source

To install from source, you need a working installation of the [Rust toolchain](https://rustup.rs/)

After installing the toolchain, run:

```sh
cargo install mdbook-autosummary
```

## Usage

To use the preprocessor, add the following to your `book.toml` file:

```toml
[preprocessor.autosummary]

# This is so that mdBook doesn't start regenerating 
# deleted folders before autosummary can remove them from SUMMARY.md
[build]
create-missing = false
```

It is additionally recommended to add `SUMMARY.md` to `.gitignore`.

### Requirements

- All folders that you want to be included in the `SUMMARY.md` **must** have an `index.md` (or equivalent) file in them. This is the file that will be linked to in the `SUMMARY.md`.
  - Folders that do not have `index.md` (or equivalent) in them will be ignored.
- All files should begin with an h1 (`# `) heading that will be used as the title of the page in the `SUMMARY.md`.
  - The file/folder's name will be used as fallback if no h1 heading is found.

### Usage with other preprocessors

> [!WARNING]
> This **must** be the first preprocessor to run, otherwise the outputs of other preprocessors may be ignored!

To ensure this, add the following to the other preprocessors in your `book.toml` file:

```toml
[preprocessor.foo]
after = ["autosummary"]
```

## Configuration

All configuration options are optional and go under the `preprocessor.autosummary` table in `book.toml`.

```toml
[preprocessor.autosummary]
# Controls the name of the index.md file that is looked for in each folder.
index-name = "index.md"
# If true, files that start with . or _ are ignored.
ignore-hidden = true
```

## Limitations

If a `SUMMARY.md` doesn't exist when `mdbook build` is run or is invalid, mdBook by default fails the build *before* calling any preprocessors.

This has the following implications:

- When deleting files or folders that were in `SUMMARY.md` before, `SUMMARY.md` has to be emptied/truncated manually to force regeneration.
- A `SUMMARY.md` must exist, even if it is empty, before running `mdbook build`.

Therefore it is recommended to not commit `SUMMARY.md` to source control and adding it to `.gitignore`. In addition, in CI/CD, an empty `SUMMARY.md` must be created before running `mdbook build`,
even with this preprocessor active.

## How does it work?

The way it works internally is a *bit* hacky due to the fact that preprocessors are not supposed to modify `SUMMARY.md` directly.

When the preprocessor is invoked, it generates a new `SUMMARY.md` in memory & compares it to the existing one. If they do not match, the generated one overwrites to existing one, and the book is reloaded from disk entirely. If they do match, the preprocessor does nothing. To my knowledge this is the only way to force `mdBook` to reparse the `SUMMARY.md` file, short of parsing & building a `Book` object yourself from scratch.

The side-effects of this approach are that mdBook is forced to reload the entire book when `SUMMARY.md` changes, and possibly invoke some preprocessors multiple times as well. (If they are defined before `mdbook-autosummary`) Also since this is a preprocessor, it is invoked for every backend that is built, although filehash comparisons are used to avoid unnecessary work.

### Why not just tell mdBook to use the new Summary you generate?

The function to do that [exists](https://github.com/rust-lang/mdBook/blob/master/src/book/book.rs#L212) in `mdBook` but is unfortunately private. Given the hacky nature of this preprocessor, I don't think it's worth the effort to make a PR to `mdBook` to make it public, instead, alternative approaches to this problem should be explored. (For example adding the ability to specify the source of a summary to be an extension/preprocessor rather than a file)

## Contributing

Contributions are welcome! Please open an issue or a PR if you have any suggestions or improvements.

### Creating new releases

1. Update the version in `Cargo.toml`
2. Update `CHANGELOG.md`
3. Push a new tag with the version number, prefixed with `v` (e.g. `v0.1.0`)
4. CD will automatically build & publish the new version to crates.io & github

mdbook-autosummary

mdbook-autosummary 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

mdbook-autosummary

mdbook-autosummary 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README