{"id":13688913,"url":"https://github.com/mlange-42/yarner","last_synced_at":"2025-03-16T08:32:46.484Z","repository":{"id":50791508,"uuid":"264313458","full_name":"mlange-42/yarner","owner":"mlange-42","description":"Literate Programming command line tool for Markdown","archived":false,"fork":false,"pushed_at":"2022-08-21T18:07:28.000Z","size":2119,"stargazers_count":32,"open_issues_count":6,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-02-27T05:56:26.508Z","etag":null,"topics":["command-line","documentation","literate-programming","markdown","rust"],"latest_commit_sha":null,"homepage":"https://mlange-42.github.io/yarner","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/mlange-42.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-05-15T22:39:35.000Z","updated_at":"2024-10-07T14:27:13.000Z","dependencies_parsed_at":"2022-08-31T11:14:13.634Z","dependency_job_id":null,"html_url":"https://github.com/mlange-42/yarner","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlange-42%2Fyarner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlange-42%2Fyarner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlange-42%2Fyarner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlange-42%2Fyarner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlange-42","download_url":"https://codeload.github.com/mlange-42/yarner/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243807431,"owners_count":20350992,"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":["command-line","documentation","literate-programming","markdown","rust"],"created_at":"2024-08-02T15:01:27.485Z","updated_at":"2025-03-16T08:32:45.950Z","avatar_url":"https://github.com/mlange-42.png","language":"Rust","funding_links":[],"categories":["documentation","Rust"],"sub_categories":[],"readme":"# Yarner\n\n[![Test status](https://github.com/mlange-42/yarner/actions/workflows/tests.yml/badge.svg)](https://github.com/mlange-42/yarner/actions/workflows/tests.yml)\n[![GitHub](https://img.shields.io/badge/github-repo-blue?logo=github)](https://github.com/mlange-42/yarner)\n[![Crate](https://img.shields.io/crates/v/yarner.svg)](https://crates.io/crates/yarner)\n[![Book](https://img.shields.io/badge/book-master-blue.svg)](https://mlange-42.github.io/yarner)\n[![MIT license](https://img.shields.io/github/license/mlange-42/yarner)](https://github.com/mlange-42/yarner/blob/master/LICENSE)\n\nA language-independent [Literate Programming](https://en.wikipedia.org/wiki/Literate_programming) tool for Markdown. From Markdown documents written and structured for humans, Yarner extracts code blocks into compilable source code. It offers sufficient features and flexibility to be usable also for larger projects with numerous files and multiple languages.\n\nYarner works with familiar syntax, which can be further customized to suit your needs exactly.\nSee the [examples](examples) directory for full working examples using different programming languages.\nSee the [**User Guide**](https://mlange-42.github.io/yarner/) for documentation.\n\n* [Features](#features)\n* [Installation](#installation)\n* [Getting started](#getting-started)\n* [Configuration](#configuration)\n* [Contributing](#contributing)\n* [Acknowledgements](#acknowledgements)\n\n## Features\n\n* Macros and named code blocks\n* Multiple files, multiple entrypoints\n* File transclusions\n* Reverse mode\n* Custom plugins\n* ...\n\nSee the [**User Guide**](https://mlange-42.github.io/yarner/) for a complete and detailed explanation of all features.\n\n## Installation\n\n**Pre-compiled binaries**\n\n1. Download the [latest binaries](https://github.com/mlange-42/yarner/releases) for your platform\n2. Unzip somewhere\n3. *Optional:* add the parent directory of the executable to your `PATH` environmental variable\n\n**Using `cargo`**\n\nIn case you have [Rust](https://www.rust-lang.org/) installed, you can install with `cargo`:\n\n```plaintext\n\u003e cargo install yarner\n```\n\n## Getting started\n\nTo set up a new project, use the `init` sub-command. Run the following in your project's base directory:\n\n```plaintext\n\u003e yarner init\n```\n\nThis creates a file `Yarner.toml` with default settings, and a file `README.md` as starting point for Literate Programming.\n\nThe generated file already contains some content to get started with Yarner's basic features. For details, see the [User Guide](https://mlange-42.github.io/yarner/).\n\nTo build the project (extract code and create documentation), simply run:\n\n```plaintext\n\u003e yarner\n```\n\nThis creates two sub-directories, one containing the extracted code (a minimal but working Rust project), and another containing the final documentation.\n\nNote that the contents of these directories can then be treated as usual, i.e. compiling the code with the normal compiler, or rendering Markdown to HTML or PDF.\n\n## Examples\n\n### Macros\n\nMacros are what enables the literate program to be written in logical order for the human reader. Using Yarner, this is accomplished by naming the code blocks, and then referencing them later by \"invoking\" the macro.\n\nBy default, macro invocations start with `// ==\u003e` and end with a period `.`. Both of these sequences can be customized to suit your needs better. The only restriction with macro invocations is that they must be the only thing on the line.\n\nHere, we have an unnamed code block as entrypoint, and \"draw\" code from two other code blocks into the main function. These code blocks are named by their first line of code, starting with `//-`.\n\n~~~markdown\nThe program starts in the main function. It calculates something and prints the result:\n\n```rust\nfn main() {\n    // ==\u003e Calculate something.\n    // ==\u003e Print the result.\n}\n```\n\nThe calculation does the following:\n\n```rust\n//- Calculate something\nlet result = 100;\n```\n\nPrinting the result looks like this:\n\n```rust\n//- Print the result\nprintln!(\"{}\", result);\n```\n~~~\n\nThe rendered document looks like this:\n\n\u003ctable\u003e\u003ctr\u003e\u003ctd\u003e\n\nThe program starts in the main function. It calculates something and prints the result:\n\n```rust\nfn main() {\n    // ==\u003e Calculate something.\n    // ==\u003e Print the result.\n}\n```\n\nThe calculation does the following:\n\n```rust\n//- Calculate something\nlet result = 100;\n```\n\nPrinting the result looks like this:\n\n```rust\n//- Print the result\nprintln!(\"{}\", result);\n```\n\n\u003c/td\u003e\u003c/tr\u003e\u003c/table\u003e\n\nThe generated code looks like this:\n\n```rust\nfn main() {\n    let result = 100;\n    println!(\"{}\", result);\n}\n```\n\n### Entrypoints\n\nBy default, the entrypoint of the program is always the unnamed code block.\nHowever, a code block name can be given in `Yarner.toml` or passed to Yarner on the command line.\nThen, instead of starting at the unnamed code block, it will start at the code block with this name.\n\nBy naming code blocks with prefix `file:` followed by a relative path, multiple code files can be created\nfrom one source file. Each code block with the `file:` prefix is treated as a separate entry point.\n\n~~~markdown\n```rust\n//- file:src/lib.rs\nfn say_hello() {\n    println!(\"Hello Literate Programmer!\");\n}\n```\n~~~\n\n[File transclusions and links](https://mlange-42.github.io/yarner/links-and-transclusions.html) are further features that allow for projects with multiple code, documentation and/or source files.\n\n## Configuration\n\nConfiguration is provided via a toml configuration file (default: `Yarner.toml`).\nA file with default configurations is generated through the `init` sub-command.\nSee the user guide chapters [configuration](https://mlange-42.github.io/yarner/configuration.html) for details on individual settings.\n\n## Contributing\n\nPlease use the [Issues](https://github.com/mlange-42/yarner/issues) for bug reports and feature suggestions. For questions and general discussion, use the [Discussions](https://github.com/mlange-42/yarner/discussions).\n\nPull requests are welcome!\n\n## Acknowledgements\n\nThis tool is derived from [foxfriends](https://github.com/foxfriends)' work [outline](https://github.com/foxfriends/outline).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlange-42%2Fyarner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlange-42%2Fyarner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlange-42%2Fyarner/lists"}