{"id":20731678,"url":"https://github.com/bgotink/mdbook-angular","last_synced_at":"2025-07-31T08:04:35.761Z","repository":{"id":179928761,"uuid":"664112790","full_name":"bgotink/mdbook-angular","owner":"bgotink","description":null,"archived":false,"fork":false,"pushed_at":"2024-10-07T11:21:22.000Z","size":529,"stargazers_count":3,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-25T08:56:49.542Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"eupl-1.2","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bgotink.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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,"zenodo":null}},"created_at":"2023-07-09T00:25:55.000Z","updated_at":"2025-07-24T14:37:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"faed2fbc-1e7d-470b-a5a2-ac7f50246d6c","html_url":"https://github.com/bgotink/mdbook-angular","commit_stats":null,"previous_names":["bgotink/mdbook-angular"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/bgotink/mdbook-angular","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgotink%2Fmdbook-angular","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgotink%2Fmdbook-angular/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgotink%2Fmdbook-angular/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgotink%2Fmdbook-angular/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bgotink","download_url":"https://codeload.github.com/bgotink/mdbook-angular/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgotink%2Fmdbook-angular/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267007833,"owners_count":24020267,"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","status":"online","status_checked_at":"2025-07-25T02:00:09.625Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-11-17T05:16:24.033Z","updated_at":"2025-07-31T08:04:35.730Z","avatar_url":"https://github.com/bgotink.png","language":"Rust","readme":"# mdbook-angular\n\nA renderer for [mdbook](https://rust-lang.github.io/mdBook/index.html) that turns angular code samples into running angular applications.\n\n## Usage\n\nInstall the `mdbook-angular` binary in your `PATH` and enable the renderer in your `book.toml` by adding an `output.angular` section.\n\nThere are two ways to include live code samples in your book.\nThe first option is to add `angular` to a typescript or javascript code block, e.g.\n\n````markdown\n```ts,angular\n// live angular sample here\n```\n````\n\nThe second option is to add a special `{{#angular}}` tag in your page that points towards a component\n\n```markdown\n{{#angular ./path/to/file.ts#NameOfExportedComponentClass}}\n\n\u003c!-- or --\u003e\n\n{{#angular ./path/to/file.ts}}\n```\n\n### Inline code blocks\n\nWhen using a code block with ` ```ts,angular`, the code block has to contain a single exported class that's a valid standalone component.\nIf the component doesn't define a selector, one will be added.\n\nThe code block will be written to a typescript (or javascript) file inside the working directory of the plugin,\nso any relative imports in the code block will not work correctly.\n\nFlags can be added to the code block in the language tag, e.g. ` ```ts,angular,hide,playground`.\n\n### The `{{#angular}}` tag\n\nThe `{{#angular}}` tag comes in two flavours: you either point towards a file, or specifically towards an export in a file.\n\nThe format of the tag is\n\n```text\n{{#angular \u003cfile\u003e[#\u003cexportName\u003e][ flag]*}}\n```\n\nSome examples:\n\n```markdown\n{{#angular ./example.ts}}\n{{#angular ./example.ts hide playground}}\n{{#angular ./example.ts#ExampleOneComponent no-playground}}\n```\n\nIf an export name is present in the tag, the file should export a standalone component with that name.\nThis component must have a selector, and that selector is expected to be unique on the page.\n\nIf no export name is present in the tag, the file should export a single standalone component.\nIf that component doesn't have a selector, one will be added.\n\nIf the `hide` flag is not set, a code block will be added at the location of the `{{#angular}}` tag.\nWhat is shown in the code block depends on whether the name of an exported component was passed or not.\nIf an export name is passed, only that class and any decorators or surrounding comments will be shown.\nIf no export name is passed, the entire file will be shown.\n\n### Live examples\n\nAll components used in the angular code blocks or imported via the `{{#angular}}` tag will be shown\nlive on the page.\nEvery component will be bootstrapped as a _separate_ angular application via [`bootstrapApplication`](https://angular.io/api/platform-browser/bootstrapApplication).\n\nIf the `no-insert` flag is not present, the live application will be added below the code block and above the playground.\nIf the `insert` flag is set, the application will not be added to the page. Instead, you will be responsible for placing the application's element somewhere on the page.\nNote angular limits you to a single instance of the component, so placing the element on the page multiple times will not work.\n\n### Playgrounds\n\nComponents running as live examples can define inputs and actions.\nIf a component has at least one input or action, a playground will be added below the live example unless disabled via flag or configuration.\n\n#### Inputs\n\nInputs are defined via Angular's `@Input()` decorator. The following limitations apply:\n\n- Input renaming is not supported\n- The input type must be limited to\n  - Text (string)\n  - Numbers\n  - Booleans\n  - Enums with string values\n\nIf the input has a default value, the type will be inferred when possible.\n\nYou can configure the input's type and default value in the playground by adding an explicit `@input` to a comment above the `@Input()` property. Immediately following the `@input` must be a valid JSON object with key \"type\" and optional key \"default\".\n\nThe following two properties will both be detected as a \"string\" input with a default value \"Bram\".\n\n```ts\n// explicit:\n\n/**\n * Author of this document\n * @input {\"type\": \"string\", \"default\": \"Bram\"}\n */\n@Input()\nauthor;\n\n// or inferred\n\n/**\n * Author of this document\n */\n@Input()\nauthor = \"Bram\";\n```\n\nYou can combine the two methods, e.g. in the following property the type will be set to the enum \"morning\" or \"evening\" and the default value will be \"evening\":\n\n```ts\n/**\n * The current time of day\n *\n * @input {\"type\": {\"enum\": [\"morning\", \"evening\"]}}\n */\n@Input()\ntimeOfDay = \"evening\";\n```\n\nThe `\"type\"` property passed in the `@input` JSON object supports the following values:\n\n- `\"string\"`\n- `\"number\"`\n- `\"boolean\"`\n- an object with a single key `\"enum\"` pointing towards an array of strings.\n\n#### Actions\n\nActions are methods on the component class that are annotated with `@action` in a comment block above the method.\n\n```ts\n/**\n * Reset the counter\n * @action\n */\nreset() {\n\tthis.counter.set(0);\n}\n```\n\n### Flags\n\nThe following flags can be passed on every angular code block:\n\n- `hide`: Don't show the code, but do include the running angular application and possibly the playground\n- `playground` / `no-playground`: Show or don't show a playground for the current application, regardless of whether the configuration allows playgrounds. The `playground` flag won't show a playground if the component doesn't warrant a playground.\n- `collapsed` / `uncollapsed`: Hide or don't hide the source code (i.e. the code block itself) in a collapsed element that can be opened via click.\n- `no-insert`: Do not automatically insert the live application on the page. This allows you to write the element linked to the angular component once (and no more than once) on the page at a location of your choosing.\n\n### Configuration\n\nYou can configure the following settings:\n\n```toml\n[output.angular]\n\n# Option defined by mdbook itself:\n\n# Executable to run, e.g. if mdbook-angular is not on your PATH\ncommand = \"/path/to/mdbook-angular\"\n\n# Options changing mdbook-angular behaviour:\n\n# Path to a directory used by mdbook-angular as temporary folder,\n# relative to the book.toml file\nworkdir = \"mdbook_angular\"\n\n# Which builder to use\n#\n# There are three to choose from:\n# - \"experimental\" (default) requires at least `@angular-devkit/build-angular`\n#   version 16.2.0. This builder builds the code for all chapters in a single go.\n# - \"slow\" works on angular ≥ 14.0.0, but it is a lot slower as it builds every\n#   chapter as a separate angular application\n# - \"background\" (not available on Windows) runs the \"experimental\" builder in a\n#   background process, which allows it to watch and rebuild instead of running\n#   an entire new build every time a change is made.\nbuilder = \"experimental\"\n\n# Whether code blocks should be collapsed by default\n#\n# This can be overridden per code block by adding either the collapsed or\n# uncollapsed flag.\n# Note this only takes effect on code blocks tagged with \"angular\", it doesn't\n# affect other code blocks.\ncollapsed = false\n\n# Whether to allow playgrounds, i.e. to add inputs and actions to the page\n# allowing your readers to interact with the running code blocks.\n#\n# This can be overridden per code block by adding either the playground or\n# no-playground flag\nplaygrounds = true\n\n# Options related to the angular build:\n\n# Path to a tsconfig file to use for the build, relative to the book.toml file.\ntsconfig = # empty by default\n\n# Language to use for inline styles\ninline-style-language = \"css\"\n\n# Whether to create an optimized angular build or not\noptimize = false\n\n# Which polyfills to load, if zone.js is not in the list then it will be loaded\n# as first polyfill\n# This is a list of strings, all of which must be bare identifiers. Relative\n# imports won't work.\npolyfills = []\n```\n\nNone of these settings are required, the default values are shown in the code above.\n\n## Development\n\nThis project requires mdbook and angular to be installed\n\n```shell\nyarn install\ncargo install mdbook\n```\n\nBuild the project\n\n```shell\ncargo build\n```\n\nThen run the following command inside the `test-book` folder\n\n```shell\nyarn exec mdbook serve\n\n# if you've got @angular/cli installed globally, you can also run\nmdbook serve\n# directly\n```\n\nand point your browser towards `http://localhost:3000`\n\n## License\n\nThis project is licensed under the European Union Public License v. 1.2 or later. The full license text can be found in `LICENSE.md`, on [the SPDX website](https://spdx.org/licenses/EUPL-1.2.html), or in any EU member language at [the website of the European Commission](https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12).\n","funding_links":[],"categories":["Third Party Components"],"sub_categories":["Markdown"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbgotink%2Fmdbook-angular","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbgotink%2Fmdbook-angular","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbgotink%2Fmdbook-angular/lists"}