{"id":13477552,"url":"https://github.com/tommilligan/mdbook-admonish","last_synced_at":"2025-05-15T09:02:29.696Z","repository":{"id":38028737,"uuid":"460253180","full_name":"tommilligan/mdbook-admonish","owner":"tommilligan","description":"A preprocessor for mdbook to add Material Design admonishments.","archived":false,"fork":false,"pushed_at":"2025-02-17T15:55:39.000Z","size":1669,"stargazers_count":199,"open_issues_count":12,"forks_count":20,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-07T04:04:48.956Z","etag":null,"topics":["mdbook","mdbook-plugins","mdbook-preprocessor","mdbook-ui"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tommilligan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-17T02:28:47.000Z","updated_at":"2025-03-23T10:35:20.000Z","dependencies_parsed_at":"2023-10-16T04:45:29.124Z","dependency_job_id":"c261d1b9-0704-4efd-a828-31ecda263ab7","html_url":"https://github.com/tommilligan/mdbook-admonish","commit_stats":{"total_commits":92,"total_committers":7,"mean_commits":"13.142857142857142","dds":"0.21739130434782605","last_synced_commit":"d97747d1952510586754952ec3b6e74fd8935e21"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tommilligan%2Fmdbook-admonish","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tommilligan%2Fmdbook-admonish/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tommilligan%2Fmdbook-admonish/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tommilligan%2Fmdbook-admonish/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tommilligan","download_url":"https://codeload.github.com/tommilligan/mdbook-admonish/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248890263,"owners_count":21178387,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mdbook","mdbook-plugins","mdbook-preprocessor","mdbook-ui"],"created_at":"2024-07-31T16:01:44.363Z","updated_at":"2025-04-14T13:43:51.212Z","avatar_url":"https://github.com/tommilligan.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# mdbook-admonish\n\n[![Latest version](https://img.shields.io/crates/v/mdbook-admonish.svg)](https://crates.io/crates/mdbook-admonish)\n[![docs.rs](https://img.shields.io/badge/docs-available-brightgreen)](https://tommilligan.github.io/mdbook-admonish/)\n\nA preprocessor for [mdbook](https://github.com/rust-lang-nursery/mdBook) to add [Material Design](https://material.io/design) admonishments, based on the [mkdocs-material](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) implementation.\n\nIt turns this:\n\n````\n```admonish info\nA beautifully styled message.\n```\n````\n\ninto this:\n\n![Simple Message](img/simple-message.png)\n\n## Examples\n\nRead the documentation [here](https://tommilligan.github.io/mdbook-admonish/), to see the actual examples in action. You can see the source in the [`./book`](./book) subdirectory.\n\nProjects using mdbook-admonish include:\n\n- [The Rhai Book](https://rhai.rs/book/) ([source](https://github.com/rhaiscript/book))\n- [The Trunk Guide](https://trunkrs.dev/guide/) ([source](https://github.com/trunk-rs/trunk))\n- [PRQL language book](https://prql-lang.org/book/) ([source](https://github.com/PRQL/prql))\n\n## Usage\n\nUse any [fenced code-block](https://spec.commonmark.org/0.30/#fenced-code-blocks) as you normally would, but annotate it with `admonish \u003cadmonition type\u003e`:\n\n````\n```admonish example\nMy example is the best!\n```\n````\n\n![Best Example](img/best-example.png)\n\nSee the [reference page](https://tommilligan.github.io/mdbook-admonish/reference.html) for a list of supported admonitions. You'll find:\n\n- `info`\n- `warning`\n- `danger`\n- `example`\n\nand quite a few more!\n\nYou can also leave out the admonition type altogether, in which case it will default to `note`:\n\n````\n```admonish\nA plain note.\n```\n````\n\n![Plain Note](img/plain-note.png)\n\n### Additional Options\n\nSee the [`mdbook-admonish` book](https://tommilligan.github.io/mdbook-admonish/) for additional options, such as:\n\n- Custom titles\n- Custom styling\n- Collapsible blocks\n\n## Installation\n\nInstall the tool:\n\n```bash\ncargo install mdbook-admonish\n\n# If you get compilation/installation errors, try a locked installation\ncargo install mdbook-admonish --locked\n```\n\nThen let `mdbook-admonish` add the required files and configuration:\n\n```bash\n# Note: this may need to be rerun for new minor versions of mdbook-admonish\n# see the 'Semantic Versioning' section below for details.\nmdbook-admonish install path/to/your/book\n\n# optionally, specify a directory where CSS files live, relative to the book root\nmdbook-admonish install --css-dir ./assets/css .\n```\n\nThis will add the following configuration to your `book.toml`:\n\n```toml\n[preprocessor.admonish]\ncommand = \"mdbook-admonish\"\n\n[output.html]\nadditional-css = [\"./mdbook-admonish.css\"]\n```\n\nand copy the file `mdbook-admonish.css` into your book's directory.\n\nThen, build your book as usual:\n\n```bash\nmdbook path/to/book\n```\n\n### Reproducible builds\n\nFor a reproducible build suitable for use in CI or scripts, please:\n\n- Pin to a specific version\n- Install with lockfile dependencies\n- Always install the latest CSS assets\n\n```bash\ncargo install mdbook-admonish --vers \"1.5.0\" --locked\nmdbook-admonish install path/to/your/book\n```\n\nThe Minimum Supported Rust Version (MSRV) is documented in `Cargo.toml`, and noted in the `CHANGELOG.md`. We aims to support around six months of stable Rust.\n\n### Updates\n\n**Please note**, when updating your version of `mdbook-admonish`, updated styles will not be applied unless you rerun `mdbook-admonish install` to update the additional CSS files in your book.\n\n`mdbook` will fail the build if you require newer assets than you have installed:\n\n```log\n2022-04-26 12:27:52 [INFO] (mdbook::book): Book building has started\nERROR:\n  Incompatible assets installed: required mdbook-admonish assets version '^2.0.0', but found '1.0.0'.\n  Please run `mdbook-admonish install` to update installed assets.\n2022-04-26 12:27:52 [ERROR] (mdbook::utils): Error: The \"admonish\" preprocessor exited unsuccessfully with exit status: 1 status\n```\n\nIf you want to update across minor versions without breakage, you should always run `mdbook-admonish install`.\n\n### Process included files\n\nYou can ensure that content inlined with `{{#include}}` is also processed by [setting the `after` option](https://rust-lang.github.io/mdBook/format/configuration/preprocessors.html#require-a-certain-order):\n\n```toml\n[preprocessor.admonish]\nafter = [\"links\"]\n```\n\nThis will expand `include` directives, before expanding `admonish` blocks.\n\n### Semantic Versioning\n\nGuarantees provided are as follows:\n\n- Major versions: Contain breaking changes to the user facing markdown API, or the public API of the crate itself.\n- Minor versions: Feature release. May contain changes to generated CSS/HTML requiring `mdbook-admonish install` to be rerun.\n  - **Note:** updating acrosss minor versions without running `mdbook-admonish install` to reinstall assets may break your build.\n  - This is due to limitations in the `mdbook` preprocessor architecture. Relevant issues that may alleviate this:\n    - https://github.com/rust-lang/mdBook/issues/1222\n    - https://github.com/rust-lang/mdBook/issues/1687\n    - https://github.com/rust-lang/mdBook/issues/1689\n- Patch versions: Bug fixes only.\n\n## Development\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on developing.\n\n## Thanks\n\nThis utility is heavily drawn from and inspired by other projects, namely:\n\n- [mdbook-mermaid](https://github.com/badboy/mdbook-mermaid)\n- [mkdocs-material](https://github.com/squidfunk/mkdocs-material)\n- [material-design-icons](https://github.com/google/material-design-icons)\n\nThe licences for these projects are included in the `licences` folder.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftommilligan%2Fmdbook-admonish","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftommilligan%2Fmdbook-admonish","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftommilligan%2Fmdbook-admonish/lists"}