{"id":13861652,"url":"https://github.com/ewels/rich-codex","last_synced_at":"2025-05-16T12:06:28.320Z","repository":{"id":43424031,"uuid":"493419550","full_name":"ewels/rich-codex","owner":"ewels","description":"Create rich code images for your docs.","archived":false,"fork":false,"pushed_at":"2025-03-14T10:43:50.000Z","size":5721,"stargazers_count":115,"open_issues_count":7,"forks_count":6,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-03T08:09:03.154Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://ewels.github.io/rich-codex/","language":"Python","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/ewels.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"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-05-17T21:31:13.000Z","updated_at":"2025-03-14T10:43:54.000Z","dependencies_parsed_at":"2024-06-18T18:32:18.059Z","dependency_job_id":"34314aac-9a1d-4504-a643-9603f1d4a287","html_url":"https://github.com/ewels/rich-codex","commit_stats":{"total_commits":323,"total_committers":11,"mean_commits":"29.363636363636363","dds":"0.31269349845201233","last_synced_commit":"eb967919edd7b95d20867180cfc4c565ab0a0cde"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ewels%2Frich-codex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ewels%2Frich-codex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ewels%2Frich-codex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ewels%2Frich-codex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ewels","download_url":"https://codeload.github.com/ewels/rich-codex/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248525138,"owners_count":21118619,"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":[],"created_at":"2024-08-05T06:01:27.257Z","updated_at":"2025-04-12T06:15:11.590Z","avatar_url":"https://github.com/ewels.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# rich-codex ⚡️📖⚡️\n\nA GitHub Action / command-line tool which generates screengrab images of a terminal window, containing _command outputs_ or _code snippets_.\n\n## 📚 Documentation: https://ewels.github.io/rich-codex/ 📚\n\n[![PyPI Version](https://img.shields.io/pypi/v/rich-codex.svg?style=flat-square)](https://pypi.python.org/pypi/rich-codex/)\n\n## Introduction\n\nHaving code examples in your documentation is a fantastic way to help users understand what to expect from your tool.\n\nUsing terminal screenshots is a good way to do this because:\n\n- 🌈 Coloured terminal output is supported\n- ↔️ You can fit in long lines without scrolling or cropping (images are auto-resized)\n- 😎 They look cool\n\nHowever, manually generating these screenshots is a pain 👎🏻 Remembering to update them every time you make a minor change means that they can easily get out of date.\n\n_**Rich-codex**_ automates this process for you. It searches markdown code for images with shell commands or code snippets. It runs these commands and saves a terminal screen-grab at the embedded path.\n\nTypical use cases:\n\n- 📷 Example CLI tool outputs that _automatically stay in sync with your package_\n- ♻️ Syntax-highlighted code snippets that are always up to date with your `examples/`\n- 🤩 Fast and simple images for your docs with minimal setup\n\n## Quickstart\n\n1. 📖 Write some markdown docs, use an image tag with a backtick command inside:\n   \u003c!-- RICH-CODEX {terminal_width: 120, notrim: true} --\u003e\n   ```markdown\n   ![`cat docs/cat.txt | lolcat -S 1`](docs/img/cat.png)\n   ```\n2. 🤖 Add a GitHub Action to automatically run the command, generate the image and commit to the repo:\n\n   ```yaml\n   on: [push]\n   jobs:\n     rich_codex:\n       runs-on: ubuntu-latest\n       steps:\n         - uses: actions/checkout@v3\n\n         - name: Install your custom tools\n           run: pip install lolcat\n\n         - name: Generate terminal images with rich-codex\n           uses: ewels/rich-codex@v1\n           with:\n             commit_changes: \"true\"\n   ```\n\n3. 🌈 Enjoy reading your documentation ![My cat rainbow](https://raw.githubusercontent.com/ewels/rich-codex/main/docs/img/cat.png)\n\n## How it works\n\nRich-codex is a command-line tool that you can run [via a GitHub action](https://ewels.github.io/rich-codex/installation/github_action/) or as a [command line tool](https://ewels.github.io/rich-codex/installation/cli/). It works with any markdown (including GitHub READMEs).\n\nIt collects either commands or code snippets, together with output filenames and configuration options. Commands are run in a subprocess and the standard output \u0026 standard error collected. These are then rendered as an image using [Textualize/rich](https://github.com/textualize/rich).\n\n\u003e Rich-codex creates the images that your markdown docs expect. It doesn't require a HTML build-step and doesn't make any changes to your markdown or its output. As such, it's compatible with _**any documentation engine**_, including rendering markdown on [github.com](https://github.com).\n\nRich-codex needs **inputs** (commands / snippets) and **output filenames** to work. These can be configured in four different ways:\n\n- 🖼 [Markdown images](https://ewels.github.io/rich-codex/inputs/markdown/)\n  - Search markdown files for image tags with command alt text. eg: `` ![`rich-codex --help`](docs/img/rich-codex-help.svg) ``\n- 💬 [Markdown comments](https://ewels.github.io/rich-codex/inputs/markdown/#code-snippets)\n  - Search markdown files for special HTML comments.\n- ➡️ [Command-line / action inputs](https://ewels.github.io/rich-codex/inputs/direct_inputs/)\n  - Specify a command or snippet using the action `with` inputs.\n- ⚙️ [Config files](https://ewels.github.io/rich-codex/inputs/config_file/)\n  - Use one or more YAML config files for multiple images and more complex customisation.\n\nImages can be generated as SVG, PNG or PDF (detected by filename extension).\n\n\u003e **Keep reading!** 👉 https://ewels.github.io/rich-codex/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fewels%2Frich-codex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fewels%2Frich-codex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fewels%2Frich-codex/lists"}