- Notifications
You must be signed in to change notification settings - Fork3
Unobtrusive literate programming experience for pragmatists
License
apiad/illiterate
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
A fast, zero-config, programmer-first literate programming tool. illiterate exports source code from Markdown files, allowing you to keep your code and documentation in one place, perfectly in sync. It's written in Rust, distributed as a single static binary, and designed to be simple, powerful, and language-agnostic.
illiterate
is bootstrapped. The best way to understand how to use it, is to read theannotated source code to learn how it works.
- Markdown as the Source of Truth: Your documentation isn't justabout the code; itis the code.
- Zero-Config by Default: No illiterate.toml or other config files needed. Everything is controlled from the command line or within the Markdown itself.
- Programmer-First: The primary goal is to generate clean, compilable source code. Beautiful documentation is a happy side effect.
- Language Agnostic: illiterate works with any programming language because it simply treats code blocks as text.
illiterate
is distributed as a single static binary for Linux (and Windows Subsystem for Linux).
You can install it by downloading the latest pre-compiled binary from theGitHub Releases page and placing it in a directory on your PATH.
The following command will install the latest version directly into/usr/local/bin
:
curl https://raw.githubusercontent.com/apiad/illiterate/refs/heads/main/install.sh| sh
That's it! Runilliterate --help
to get started.
Create a Markdown file namedmy_app.md
:
# My Awesome ApplicationThis is the main entry point for our program.```rust {export=src/main.rs}fn main() { println!("Hello, Literate World!"); <<add_a_goodbye_message>>}```And here's a reusable code fragment that we'll inject into `main`.```rust {name=add_a_goodbye_message}println!("Goodbye!");```
Runilliterate
to export the file:
illiterate my_app.md
A new file,src/main.rs
, has been created with the following content:
fnmain(){println!("Hello, Literate World!");println!("Goodbye!");}
illiterate
works by parsing special attributes inside your fenced code blocks.
A code block marked with{export=path/to/file.ext}
will have its contents extracted and appended to the specified file. All blocks targeting the same file are concatenated in the order they appear.
```python {export=app/main.py}import utils```
A code block can be given a name with{name=my_fragment}
. This block is not exported directly but can be included elsewhere using the<<my_fragment>>
syntax. This allows you to explain code in logical chunks, out of order, and assemble it correctly later.
```rust {name=setup_database}// Logic to connect to the database...``````rust {export=src/main.rs}fn main() { // Setup the database first <<setup_database>>}```
For simple cases where one Markdown file corresponds to one source file, you can use a headless{export}
attribute. illiterate will automatically generate the filename based on the Markdown file's name and the code block's language.
Given a file named my_module.md:
```rust {export}pub fn public_function() { // ...}```
Running illiterate my_module.md will create the file my_module.rs.
illiterate [OPTIONS] [FILES...]
- [FILES...]: One or more Markdown files to process.
- --dir: Sets the root output directory for all exported files. Defaults to the current directory.
- --test: Tests the output against generated files, without generating anything. Exists with zero if the generated files would not change. Useful for CI/CD.
- Add flag
--test
to test the output against generated files.
- First version with full support for named references and headless exporting.
- Basic markdown parsing and extraction of simple blocks.
Here are some of the planned features to make illiterate even more powerful. You are welcome to contribute to any of them!
A dry run mode that shows what files would be created and their contents without actually writing them to disk.
- Command:
illiterate --dry [FILES...]
- Functionality: Outputs the list of files that would be created and their contents.
A picture is worth a thousand lines of code. This feature will generate a visual map of your project's structure.
- Command:
illiterate --graph [FILES...]
- Functionality: Outputs aGraphviz dot language representation of the project. It will map the relationships between all {export=...} targets and the {name=...} fragments they include.
- Example:
illiterate --graph my_app.md | dot -Tpng > architecture.png
This provides a "reverse export" to keep the Markdown source of truth synchronized with small, quick changes made directly to the generated code.
- Command:
illiterate -u, --update [FILES...]
- Functionality: illiterate will read the content of the on-disk source files. If a file differs from whatwould have been generated, this command willupdate the corresponding code block in the Markdown file to match the on-disk version. This is perfect for backporting quick fixes without manual copy-pasting.
To provide a seamless, real-time development experience, illiterate will function as a Language Server Protocol (LSP) server.
- Command:
illiterate --lsp
- Functionality: This command launches the LSP server. When used with a compatible editor plugin, it enables:
- Error Diagnostics: Underlines includes of non-existent fragments.
- Go to Definition: F12 on
<<my_fragment>>
jumps to its definition. - Completions: Autocompletes fragment names as you type <<....
- Hover Information: Shows a fragment's content when you hover over it.
This project is self-hosting! The source code for illiterate lives in illiterate.md and is exported to the src/ directory, which is checked into version control.
The workflow for contributors is simple:
- Clone the repository:
git clone https://github.com/apiad/illiterate.gitcd illiterate
- Build the initial version: The src/ directory contains pre-exported source code, so you can build it immediately.
cargo build
This creates a binary attarget/debug/illiterate
.
Make your changes: Edit the "source of truth" file,
illiterate.md
.Re-export the source code: Use the binary you just built to update the
src/
directory with your changes.
make self
- Run your tests:
maketest
- Rinse and repeat until done. Then push and send a PR.
illiterate
is licensed under theMIT License. See theLICENSE file for details.
About
Unobtrusive literate programming experience for pragmatists
Topics
Resources
License
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Contributors3
Uh oh!
There was an error while loading.Please reload this page.