{"id":26485188,"url":"https://github.com/reecepbcups/docci","last_synced_at":"2026-05-11T09:18:26.656Z","repository":{"id":282787890,"uuid":"949241772","full_name":"Reecepbcups/docci","owner":"Reecepbcups","description":"Your documentation is now your test suite","archived":false,"fork":false,"pushed_at":"2025-03-17T00:19:25.000Z","size":69,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-17T00:23:14.621Z","etag":null,"topics":["ci","documentation","integration-testing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Reecepbcups.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-16T01:51:32.000Z","updated_at":"2025-03-16T23:11:28.000Z","dependencies_parsed_at":"2025-03-17T04:45:49.641Z","dependency_job_id":null,"html_url":"https://github.com/Reecepbcups/docci","commit_stats":null,"previous_names":["reecepbcups/docci"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Reecepbcups%2Fdocci","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Reecepbcups%2Fdocci/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Reecepbcups%2Fdocci/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Reecepbcups%2Fdocci/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Reecepbcups","download_url":"https://codeload.github.com/Reecepbcups/docci/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244560351,"owners_count":20472219,"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":["ci","documentation","integration-testing"],"created_at":"2025-03-20T05:55:43.713Z","updated_at":"2026-05-11T09:18:26.645Z","avatar_url":"https://github.com/Reecepbcups.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Docci | Readme Test 🚀 \u0026middot; [![GitHub license](https://img.shields.io/badge/license-apache-blue.svg)](https://github.com/Reecepbcups/docci/blob/main/LICENSE) [![Tests](https://github.com/Reecepbcups/docci/actions/workflows/go-unit-test.yml/badge.svg)](https://github.com/Reecepbcups/docci/actions/workflows/test.yml) [![Compatible](https://img.shields.io/badge/compatible%20-macOS_\u0026_linux-8A2BE2.svg)](https://github.com/Reecepbcups/docci)\n\nYour documentation is now your test suite! 🎯 *(pronounced \"doc-ee\", short for documentation CI)*\n\nA CI tool that brings your markdown docs to life by executing code blocks in sequence. Run processes in the background, handle environment variables, add delays, verify outputs, and modify files - all through simple markdown tags. Perfect for ensuring your docs stay accurate and your examples actually work! 📚\n\n## 🌟 Projects Using Docci\n\nSeveral projects have adopted Docci to ensure their documentation stays accurate and executable:\n\n- **[Spawn](https://github.com/rollchains/spawn)** - Rapid Cosmos blockchain development framework\n- **[WAVS](https://github.com/Lay3rLabs/wavs-middleware)** - Eigenlayer AVS WebAssembly development\n- **[OndoChain](https://ondo.finance/ondo-chain/)** - Institutional RWA Cosmos-EVM blockchain\n\n## 🏃‍♂️ Quick Start\n\nFind sample workspaces in the [`examples/` directory](./examples/).\n\n### 📦 Installation\n\n[Go `1.23`+](https://go.dev/doc/install) is required. You can also download a pre-built binary from the [release page](https://github.com/Reecepbcups/docci/releases).\n\n```bash docci-ignore\ngo install github.com/reecepbcups/docci\n```\n\n```bash docci-ignore\ngit clone git@github.com:Reecepbcups/docci.git --depth 1\ncd docci\ngo mod tidy\ntask install # go install ./*.go\n```\n\n### 🤖 Github Actions Integration\n````yaml\n  # docci_Linux_x86_64, docci_Linux_arm64, docci_Darwin_x86_64, docci_Darwin_arm64\n  - name: Install Docci Readme Test Tool\n    run: |\n      VERSION=v0.9.2\n      BINARY=docci_Linux_x86_64.tar.gz\n      curl -fsSL \"https://github.com/Reecepbcups/docci/releases/download/${VERSION}/${BINARY}\" | sudo tar -xzC /usr/local/bin\n      sudo chmod +x /usr/local/bin/docci\n\n  - run: docci run YOUR_MARKDOWN_FILE.md --hide-background-logs\n````\n\n### 🎮 Usage\n\n```bash docci-ignore\ndocci run \u003cmarkdown_file.md\u003e [options]\n\ndocci run nested/README.md --hide-background-logs\ndocci run A.md --cleanup-commands \"docker-compose down\" --cleanup-commands \"rm -rf /tmp/test\"\ndocci run A.md --pre-commands \"npm install\"\n\ndocci tags\n\ndocci version\n```\n\n### 🎨 Operation tags\n  * 🛑 `docci-ignore`: Skip executing this code block\n  * 🔄 `docci-background`: Run the command in the background\n  * 💀 `docci-background-kill=N`: Kill a previously started background process by index (1-based)\n  * 🚫 `docci-if-not-installed=BINARY`: Skip execution if some binary is installed (e.g. node)\n  * ⏲️ `docci-delay-before=N`: Wait N seconds before running any commands in the block\n  * ⏲️ `docci-delay-after=N`: Wait N seconds after running all commands in the block\n  * ⌛ `docci-delay-per-cmd=N`: Wait N seconds before each command\n  * ⏲️ `docci-retry=N`: Retry command N times *(pair with docci-delay-per-cmd)*\n  * 🌐 `docci-wait-for-endpoint=http://localhost:8080/health|N`: Wait up to N seconds for the endpoint to be ready\n  * 📜 `docci-output-contains=\"string\"`: Ensure the output contains a string at the end of the block (also use `=''`)\n  * 🚨 `docci-assert-failure`: If it is expected to fail (non 0 exit code)\n  * 🖥️ `docci-os=mac|linux`: Run the command only on it's the specified OS\n  * 🔄 `docci-replace-text=\"old;new\"`: Replace text in the code block before execution (including env variables!)\n\n### 📄 File Tags\n  * 📝 `docci-file`: The file name to operate on\n  * 🔄 `docci-reset-file`: Reset the file to its original content\n  * 🚫 `docci-if-file-not-exists`: Only run if a file does not exist\n  * ➕ `docci-line-insert=N`: Insert content at line N\n  * ✏️ `docci-line-replace=N`: Replace content at line N\n  * 📋 `docci-line-replace=N-M`: Replace content from line N to M\n\n\n### 💡 Code Block Tag Examples (Operations)\n\nSkip needless installations if you are already set up: 🛑\n\n\u003c!-- The 4 backticks is just so it wraps in githubs UI, real test are written normally with the nested part (just 3 backticks) --\u003e\n````bash\n```bash docci-os=linux docci-if-not-installed=node\n# this only runs if `node` is not found in the system \u0026 it's a linux system\ncurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.2/install.sh | bash\nexport NVM_DIR=\"$HOME/.nvm\"\nnvm install v21.7.3\n```\n````\n\nEnsure the output (stdout or stderr) contains a specific string: 📜\n\n````bash\n```bash docci-contains=\"xyzMyOutput\"\necho xyzMyOutput\n```\n````\n\nRun blocking commands in the background: 🌐\n\n````bash\n```bash docci-background docci-delay-after=2\ngo run examples/server_endpoint/test_server.go 3000\n```\n````\n\nAdd delays between commands for stability after the endpoint from a previous command is up: ⏱️\n\n````bash\n```bash docci-output-contains=\"GOOD\" docci-wait-for-endpoint=http://localhost:3000/health|5\nVALUE=$(curl http://localhost:3000/health)\necho \"Got value: $VALUE\"\n```\n````\n\n\nAssert that a command fails: 🚨\n\n````bash\n```bash docci-assert-failure\nnotinstalledbin --version\n```\n````\n\nSet ENV Variables\n\n````bash\n```bash\nexport SOME_ENV_VAR=\"abcdef\"\nOTHER_ENV_VAR=\"ghijkl\"\necho \"SOME_ENV_VAR is $SOME_ENV_VAR and OTHER_ENV_VAR is $OTHER_ENV_VAR\"\n```\n````\n\nDocci automatically sets `IS_DOCCI_RUN=true` for all executed commands:\n\n````bash\n```bash\n# This environment variable is automatically set by docci\nif [ \"$IS_DOCCI_RUN\" = \"true\" ]; then\n    echo \"Running inside docci!\"\nfi\n```\n````\n\nReplace text before execution (useful for CI/CD): 🔄\n\n````bash\n```bash docci-replace-text=\"API_KEY;$SOME_ENV_VAR\"\necho \"Imagine a cURL request with API_KEY here\"\n```\n````\n\nCleanup demo server if running in the background:\n\n````bash\n```bash\ncurl http://localhost:3000/kill\n```\n````\n\n### 💡 Files Code Block Tag Examples\n\nCreate a new file from content: 📝\n\n\u003c!-- yes, the typo is meant to be here --\u003e\n````html\n```html docci-file=example.html docci-reset-file\n\u003chtml\u003e\n    \u003chead\u003e\n        \u003ctitle\u003eMy Titlee\u003c/title\u003e\n    \u003c/head\u003e\n\u003c/html\u003e\n```\n````\n\nReplace the typo'ed line:\n\n````html\n```html docci-file=example.html docci-line-replace=3\n        \u003ctitle\u003eMy Title\u003c/title\u003e\n```\n````\n\nAdd new content\n\n````html\n```html docci-file=example.html docci-line-insert=4\n    \u003cbody\u003e\n        \u003ch1\u003eMy Header\u003c/h1\u003e\n        \u003cp\u003e1 paragraph\u003c/p\u003e\n        \u003cp\u003e2 paragraph\u003c/p\u003e\n    \u003c/body\u003e\n```\n````\n\nReplace multiple lines\n\n````html\n```html docci-file=example.html docci-line-replace=7-9\n        \u003cp\u003eFirst paragraph\u003c/p\u003e\n        \u003cp\u003eSecond paragraph\u003c/p\u003e\n```\n````\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freecepbcups%2Fdocci","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freecepbcups%2Fdocci","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freecepbcups%2Fdocci/lists"}