{"id":18234058,"url":"https://github.com/kvankova/code-embedder","last_synced_at":"2025-08-18T13:03:51.882Z","repository":{"id":258811584,"uuid":"875303283","full_name":"kvankova/code-embedder","owner":"kvankova","description":"Keep your code snippets in README up-to-date!","archived":false,"fork":false,"pushed_at":"2025-03-04T14:02:36.000Z","size":12622,"stargazers_count":65,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-19T17:03:50.590Z","etag":null,"topics":["code-synchronization","github-action","github-action-docker","github-actions","readme"],"latest_commit_sha":null,"homepage":"","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/kvankova.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":"2024-10-19T16:13:52.000Z","updated_at":"2025-03-10T12:20:11.000Z","dependencies_parsed_at":"2024-11-03T19:25:42.838Z","dependency_job_id":"31d4219d-67b3-4871-843b-efb1addf4666","html_url":"https://github.com/kvankova/code-embedder","commit_stats":null,"previous_names":["kvankova/code-embedder"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kvankova%2Fcode-embedder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kvankova%2Fcode-embedder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kvankova%2Fcode-embedder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kvankova%2Fcode-embedder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kvankova","download_url":"https://codeload.github.com/kvankova/code-embedder/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247076084,"owners_count":20879607,"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":["code-synchronization","github-action","github-action-docker","github-actions","readme"],"created_at":"2024-11-04T17:03:18.848Z","updated_at":"2025-04-03T20:33:08.343Z","avatar_url":"https://github.com/kvankova.png","language":"Python","readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/front.png\" alt=\"Image\" /\u003e\n\n## **Code Embedder**\nSeamlessly update code snippets in your **README** files! 🔄📝🚀\n\n[Description](#-description) • [How it works](#-how-it-works) • [Setup - Github Action](#-setup---github-action) • [Setup - Pre-commit Hook](#-setup---pre-commit-hook) • [Examples](#-examples) • [Contributing](#-contributing) • [Development](#️-development)\n\u003c/div\u003e\n\n\n## 📚 Description\n\n**Code Embedder** is a **GitHub Action** and a **pre-commit hook** that automatically updates code snippets in your markdown (`README`) files. It finds code blocks in your `README` that reference specific scripts, then replaces these blocks with the current content of those scripts. This keeps your documentation in sync with your code.\n\n### ✨ Key features\n- 🔄 **Automatic synchronization**: Keep your `README` code examples up-to-date without manual intervention.\n- 🛠️ **Easy setup**: Simply add the action to your GitHub workflow / pre-commit hook and format your `README` code blocks.\n- 📝 **Section support**: Update only specific sections of the script in the `README`. This is **language agnostic**.\n- 🧩 **Object support**: Update only specific objects (functions, classes) in the `README`. *The latest version supports only 🐍 Python objects (other languages to be added soon).*\n\n\nBy using **Code Embedder**, you can focus on writing and updating your actual code 💻, while letting the Code-Embedder take care of keeping your documentation current 📚🔄. This reduces the risk of outdated or incorrect code examples in your project documentation.\n\n## 🔍 How it works\n\nThe **Code Embedder** scans markdown files for special tags that specify which parts of your scripts to embed. When it finds these tags, it automatically updates the code blocks with the latest content from your source files. When used as a GitHub Action, any changes are automatically committed and pushed to your repository 🚀.\n\n### 📄 **Full script** updates\nIn the `README` (or other markdown) file, the full script is marked with the following tag:\n````md\n ```language:path/to/script\n ```\n````\n### 📂 **Section** updates\nIn the `README` (or other markdown) file, the section of the script is marked with the following tag:\n````md\n ```language:path/to/script:s:section_name\n ```\n````\n\u003e [!Note]\n\u003eNotice that the `path/to/script` is followed by `s:` in the tag to indicate that the section `section_name` is being updated.\n\nYou must also add the following comment tags in the script file `path/to/script`, where the section is located:\n```\n[Comment sign] code_embedder:section_name start\n...\n[Comment sign] code_embedder:section_name end\n```\nThe comment sign is the one that is used in the script file, e.g. `#` for Python, or `//` for JavaScript. For example, in python script you add `# code_embedder:A start` and `# code_embedder:A end` to new lines to mark the start and end of the section `A` you want to include in the `README`.\n\nThe `section_name` must be unique in the file, otherwise the Code-Embedder will use the first section found.\n\n### 🧩 **Object** updates\nIn the `README` (or other markdown) file, the object of the script is marked with the following tag:\n````md\n ```language:path/to/script:o:object_name\n ```\n````\n\u003e [!Note]\n\u003e Notice that the `path/to/script` is followed by `o:` in the tag to indicate that the object `object_name` is being updated.\n\n\u003e [!Note]\n\u003e The object name must match exactly the name of the object (function, class) in the script file, including the case (e.g. if class is `Person` then object name must be `Person`, not `person`). Currently, only 🐍 Python objects are supported.\n\n## 🔧 Setup - Github Action\nUse **Code Embedder** as a Github Action by adding the following to your `.github/workflows/code-embedder.yaml` file:\n\n```yaml\nname: Code Embedder\n\non: pull_request\n\npermissions:\n  contents: write\n\njobs:\n  code_embedder:\n    name: \"Code embedder\"\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n        with:\n          ref: ${{ github.event.pull_request.head.ref }}\n\n      - name: Run code embedder\n        uses: kvankova/code-embedder@v1.1.2\n        env:\n          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n\n```\n\n## 🔧 Setup - Pre-commit Hook\nYou can set up **Code Embedder** as a pre-commit hook using either:\n\u003col type=\"A\"\u003e\n   \u003cli\u003eInstallation via PyPI\u003c/li\u003e\n   \u003cli\u003eDirect repository reference in your \u003ccode\u003e.pre-commit-config.yaml\u003c/code\u003e file\u003c/li\u003e\n\u003c/ol\u003e\n\n### A. Installation via PyPI\nInstall the package:\n```bash\npip install code-embedder==v1.1.2\n```\n\nYour `.pre-commit-config.yaml` file should look like this:\n```yaml\n- repo: local\n  hooks:\n    - id: code-embedder\n      name: Code embedder\n      entry: code-embedder run\n      language: system\n```\n\n### B. Direct repository reference\nAlternatively, you can reference the repository directly in your `.pre-commit-config.yaml` file:\n```yaml\n- repo: https://github.com/kvankova/code-embedder\n  rev: v1.1.2\n  hooks:\n    - id: code-embedder\n      name: Code embedder\n      entry: code-embedder run\n      language: system\n```\n\n### 🔧 Options\nCommand `code-embedder run` has the following options:\n\n| Option | Description |\n| ------ | ----------- |\n| `--all-files` | Process all files in the repository. In pre-commit hook, it by default checks only the changed files. |\n\n## 💡 Examples\n\n### 📄 Full script update\n\nLet's say you have the following `README` file:\n````md\n# README\n\nThis is a readme.\n\n```python:main.py\n```\n````\nThe `main.py` file contains the following code:\n```python\nprint(\"Embedding successful\")\n```\n\nOnce code-embedder runs, the code block sections are filled with the content of the script located at `main.py` and updated in the `README` file.\n\n````md\n# README\n\nThis is a readme.\n\n```python:main.py\nprint(\"Embedding successful\")\n```\n````\nWith any changes to `main.py`, the code block section is updated in the `README` file with the next code-embedder run.\n\n### 📂 Section update\n\nNow we have the following `README` file:\n````md\n# README\n\nThis is a readme.\n\n```python:main.py:s:A\n```\n````\nThe `main.py` file contains the following code:\n```python\nprint(\"Hello, world!\")\n\n# code_embedder:A start\nprint(\"Embedding successful\")\n# code_embedder:A end\n```\n\nOnce code-embedder runs, the code block section will be updated in the `README` file with the content of the section `A` from the script located at `main.py` (in case of using it as a Github Action, the changes are then pushed to the repository 🚀).\n\n````md\n# README\n\nThis is a readme.\n\n```python:main.py:s:A\nprint(\"Embedding successful\")\n```\n````\n\nWith any changes to the section `A` in `main.py`, the code block section is updated in the `README` file with the next code-embedder run.\n\n### 🧩 Object update\nThe tag used for object update follows the same convention as the tag for section update with the following changes:\n- use `o:` instead of `s:`\n- use `object_name`\n\n\u003e [!Note]\n\u003e The `object_name` must match exactly the name of the object (function, class) in the script file, including the case. If you define class `Person` in the script, you must use `Person` as the object name in the `README`, not lowercase `person`.\n\nFor example, let's say we have the following `README` file:\n````md\n# README\n\nThis is a readme.\n\nFunction `print_hello` is defined as follows:\n```python:main.py:o:print_hello\n```\n\nClass `Person` is defined as follows:\n```python:main.py:o:Person\n```\n````\n\nThe `main.py` file contains the following code:\n```python\n...\ndef print_hello():\n    print(\"Hello, world!\")\n...\n\nclass Person:\n    def __init__(self, name):\n        self.name = name\n    def say_hello(self):\n        print(f\"Hello, {self.name}!\")\n...\n```\n\nOnce code-embedder runs, the code block section will be updated in the `README` file with the content of the function `print_hello` and class `Person` from the script located at `main.py` (in case of using it as a Github Action, the changes are then pushed to the repository 🚀).\n\n````md\n# README\n\nThis is a readme.\n\nFunction `print_hello` is defined as follows:\n```python:main.py:o:print_hello\ndef print_hello():\n    print(\"Hello, world!\")\n```\n\nClass `Person` is defined as follows:\n```python:main.py:o:Person\nclass Person:\n    def __init__(self, name):\n        self.name = name\n    def say_hello(self):\n        print(f\"Hello, {self.name}!\")\n```\n````\n\nWith any changes to the function `print_hello` or class `Person` in `main.py`, the code block sections are updated in the `README` file with the next code-embedder run.\n\n## 🤝 Contributing\nWe welcome contributions to improve this package!\n- If you have an idea for a **new feature** ✨, open a [new feature request](https://github.com/kvankova/code-embedder/issues/new?labels=enhancement\u0026template=feature_request.yaml) on GitHub.\n- If you spot a **bug** 🐛, open a [new issue](https://github.com/kvankova/code-embedder/issues/new/choose) on GitHub.\n- If you want to **contribute to the code**, please pick an issue that is not assigned to anyone and comment on it, so that we know you are working on it.\n\n## 🛠️ Development\n1. Fork this project\n1. Install [poetry](https://python-poetry.org/docs/#installation)\n1. Install the dependencies by using the following command:\n    ```bash\n    poetry install --with dev\n    ```\n1. Make changes to the codebase and run the tests to make sure everything works as expected. ✅\n    ```bash\n    poetry run pytest\n    ```\n1. Commit your changes, push them to the repository 🚀, and open a new pull request.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkvankova%2Fcode-embedder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkvankova%2Fcode-embedder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkvankova%2Fcode-embedder/lists"}