Metadata-Version: 2.4
Name: markdown-code-snippet
Version: 0.0.1.dev2
Summary: Inject snippets of files or python code into Markdown files.
Author: confarg
Author-email: confarg <280620574+confarg@users.noreply.github.com>
License-Expression: MPL-2.0
License-File: LICENSE
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# markdown-code-snippet

> Inject snippets of files or Python code into Markdown files.

## Install

In your `.pre-commit-hooks.yaml`:

```yaml
repos:
  - repo: https://github.com/confarg/markdown-code-snippet
    rev: v0.0.1.dev1
    hooks:
      - id: markdown-code-snippet
```

You can also install it as a project dependency:

```bash
uv add --dev markdown-code-snippet
```

```yaml
repos:
  - repo: local
    hooks:
      - id: markdown-code-snippet
        entry: uv run markdown-code-snippet
        language: system
```

## Inject code snippets into Markdown

The tool works by reading instructions provided in HTML comments placed before a code block. The content of the code block will be overwritten during each pre-commit run.

To include a whole file:

````markdown
<!-- snippet: path/to/config.yaml -->
```yaml
db:
  port: 5432
```
````

To include a specific class:

````markdown
<!-- snippet: path/to/foo.py#Foo -->
```python
@dataclass
class Foo:
  id: int
```
````

Note that class decorators, if any, are included in the snippet.

To include a specific method:

````markdown
<!-- snippet: path/to/bar.py#Bar.get_value -->
```python
def get_value(self):
    return self.value
```
````

Note that code snippets are dedented by default. Add `dedent=false` to the info string to disable it.

To include a specific top-level definition:

````markdown
<!-- snippet: path/to/baz.py#BAZ -->
```python
BAZ: int = 42
```
````

Finally, if you want to copy-paste a random snippet that cannot be expressed as a single class, function or definition, you can opt to modify your code specifically for this purpose and add anchors, like so:

```python
# [snippet: increase_qux]
qux = some_func()
qux += 1  # always increase qux by 1
# [/snippet]
```

You can then specify the snippet the usual way

````markdown
<!-- snippet: path/to/qux.py#increase_qux -->
```python
qux = some_func()
qux += 1  # always increase qux by 1
```
````

> [!NOTE]
> Make sure the snippet name does not collide with another symbol declared in the file.


## Paths

Relative paths are relative to the Markdown file that carries the annotation. A leading `/`
means the project root: the nearest directory above with a `pyproject.toml`, `.git`, or `.jj`,
or whatever directory `--root` names:

```text
# docs/guide/install.md
<!-- snippet: config.yaml -->        ->  docs/guide/config.yaml
<!-- snippet: ../shared/a.yaml -->   ->  docs/shared/a.yaml
<!-- snippet: /src/app.py#main -->   ->  <project root>/src/app.py
```

## Why this tool?

I was looking for a tool that copies parts of my code into my Markdown files, so that documentation always stays up-to-date. I wanted the committed Markdown to be functional, so that browsing GitHub would provide all the information and, at the same time, be usable by MkDocs or Zensical. Therefore I needed a tool where:

- the copy of code snippets happens during pre-commit;
- the copy instructions are invisible during Markdown rendering;
- the info string (the text after the opening code fence) stays in the hands of the user, e.g. to add `title:` information.
