# Buildsheet autogenerated by ravenadm tool -- Do not edit.

NAMEBASE=		python-markdown-include
VERSION=		0.8.1
KEYWORDS=		python
VARIANTS=		v12 v13
SDESC[v12]=		Include extension for Markdown (3.12)
SDESC[v13]=		Include extension for Markdown (3.13)
HOMEPAGE=		none
CONTACT=		Python_Automaton[python@ironwolf.systems]

DOWNLOAD_GROUPS=	main
SITES[main]=		PYPIWHL/d7/e2/c4d20b21a05fe0fee571649cebc05f7f72e80b1a743f932e7326125e6c9e
DISTFILE[1]=		markdown_include-0.8.1-py3-none-any.whl:main
DIST_SUBDIR=		python-src
DF_INDEX=		1
SPKGS[v12]=		single
SPKGS[v13]=		single

OPTIONS_AVAILABLE=	PY312 PY313
OPTIONS_STANDARD=	none
VOPTS[v12]=		PY312=ON PY313=OFF
VOPTS[v13]=		PY312=OFF PY313=ON

DISTNAME=		markdown_include-0.8.1.dist-info

GENERATED=		yes

[PY312].RUN_DEPENDS_ON=			python-Markdown:single:v12
[PY312].USES_ON=			python:v12,wheel

[PY313].RUN_DEPENDS_ON=			python-Markdown:single:v13
[PY313].USES_ON=			python:v13,wheel

[FILE:3201:descriptions/desc.single]
# Markdown-Include

This is an extension to [Python-Markdown]
which provides an "include" function, similar to that found in
LaTeX (and also the C pre-processor and Fortran). I originally wrote it for
my
[FORD] Fortran auto-documentation generator.

## Installation
This module can now be installed using pip.

    pip install markdown-include

## Tests
Use the unittest module
```bash
python -m unittest discover unittests/
```

## Usage
This module can be used in a program in the following way:

```python
import markdown
html = markdown.markdown(source, extensions=['markdown_include.include'])
```

Markdown-Include can also be included in MkDocs projects like below:

```yaml
markdown_extensions:
    - markdown_include.include:
        base_path: docs
`

The syntax for use within your Markdown files is {!filename!}``. This
statement will be replaced by the contents of filename. Markdown-Include
will work recursively, so any included files within filename will also be
included. This replacement is done prior to any other
Markdown processing, so any Markdown syntax that you want can be used
within
your included files. Note that this is a change from the previous version.
It was felt that this syntax was less likely to conflict with any code
fragments present in the Markdown.

By default, all file-names are evaluated relative to the location from
which
Markdown is being called. If you would like to change the directory
relative to
which paths are evaluated, then this can be done by specifying the
extension
setting base_path.

### Line Ranges

You can also define specific lines or line ranges to include by specifying
`lines`:

```Markdown
{!filename!lines=1  3 8-10  2}
```

`lines` takes a sequence of integers separated by spaces (one or more), or
it can also
take line ranges specified with a start line and an end line separated by a
dash (`-`).

In the example above, it would read the file called `filename` and include
the lines
`1`, `3`, `8`, `9`, `10`, `2`.

Notice that line `9` was not explicitly set. But it was still included as
part of the
range `8-10`.

Also, notice that line `2` is set *after* the range `8-10`. This means that
the
line `2` in `filename` will be included *after* (below) the range `8-10`.

You can use this to include lines in a different order than the original
file. But it
also means that if you want to preserve the original order, you have to pay
attention
to the order in which you specify the lines.

## Configuration

The following settings can be specified when initialising the plugin.

- __base_path__: Default location from which to evaluate relative
  paths for the include statement. (Default: the run-directory.)
- __encoding__: Encoding of the files used by the include statement.
(Default: utf-8.)
- __inheritHeadingDepth__ : If true, increases headings on include
  file by amount of previous heading. Combiens with headingOffset
  option, below. (Default: False.)
- __headingOffset__: Increases heading depth by a specific ammount, in
  addition to the inheritHeadingDepth Option. (Default: 0)
- __throwException__: When true, if the extension is unable to find an
  included file it will throw an exception which the user can


[FILE:129:distinfo]
32f0635b9cfef46997b307e2430022852529f7a5b87c0075c504283e7cc7db53        18837 python-src/markdown_include-0.8.1-py3-none-any.whl