Metadata-Version: 2.1
Name: edition
Version: 1.0.0a4
Summary: Lightweight documentation generator
Home-page: https://github.com/cariad/edition
Author: Cariad Eccleston
Author-email: cariad@cariad.earth
License: MIT
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dinject (~=1.2)
Requires-Dist: markdown (~=3.3.4)
Requires-Dist: pygments (~=2.10)
Requires-Dist: python-frontmatter (~=1.0)

# 📰 Edition

**WARNING: This is a pre-release project.**

**Edition** is a command-line application for creating beautiful HTML and Markdown editions of your projects' documentation.

In fact, the document you're reading right now was pressed by Edition.

<edition value="toc" />

## Highlights

- **Write your documentation once.**<br />Edition will press you a `README.md` to upload to your project, PyPI et al, _and_ a beautiful HTML page ready to upload directly to GitHub or GitLab Pages.
- **Works out of the box.**<br />With one command, your existing `README.md` can be converted to beautiful HTML.
- **Embed your code samples.**<br />Edition will execute your code and embed the results.

## Getting started

### Prerequisites

Edition requires **Python 3.8** or later.

### Installation

Install Edition via `pip`:

```bash
pip install edition
```

### Quick-start example

Create this Markdown document as `example-source.md`:

~~~markdown
# Edition example

Save this file to your local machine as `example-source.md`
then run:

```bash
edition example-source.md example.html --press html
```

Now open `example.html` in a web browser. The code example
below will be complete.

```bash
python --version
```

<!--edition-exec-->
~~~

Run:

```bash
edition docs/example-source.md docs/example.html --press html
```

<!--edition-exec as=markdown fence=backticks host=shell range=start-->

```text
warning: no value for "author"
warning: no value for "favicon-emoji"
Pressed: docs/example.html
```

<!--edition-exec range=end-->

Fun fact! The execution example above is executed every time I press this documentation. That means you can see the actual [example.html](https://cariad.github.io/edition/example.html) that was generated.

## Usage

### Command line

Edition takes three command line arguments:

- Source file
- Destination file
- `--press html` to press HTML or `--press markdown` to press Markdown

### Creating your source document

Your **source document** is the Markdown document from which all your editions will be pressed.

Any Markdown document you already have -- like your project's `README.md` -- is already a valid source document, but we can add some front matter and additional markup to help guide the presses.

#### Front matter

The following front matter properties come into play only when pressing HTML.

| Property      | Description             | Default           |
| :------------ | :---------------------- | :---------------- |
| author        | Author name             | No author         |
| favicon-emoji | Emoji to use as favicon | No favicon        |
| title         | Page title              | Top-level heading |

For example:

```markdown
---
author: Cariad Eccleston
favicon-emoji: 🍕
# If "title" was omitted then the top-level "Example"
# heading would be used instead:
title: Embedded Example

---
# Example
```

#### Markup

##### Code execution

To have Edition execute your code then embed the result:

1. Create a regular Markdown code block
1. Add `<!--edition-exec-->` after the block

For example:

~~~markdown
```python
print("Hello, world!")
```

<!--edition-exec-->
~~~

Currently only `bash` and `python` code blocks are supported. More languages can be added if they are [requested](#contributing).

##### Table of Contents

```html
<edition value="toc" />
```

## Project

### Contributing

To contribute a bug report, enhancement or feature request, please raise an issue at [github.com/cariad/edition/issues](https://github.com/cariad/edition/issues).

If you want to contribute a code change, please raise an issue first so we can chat about the direction you want to take.

### Licence

Edition is released at [github.com/cariad/edition](https://github.com/cariad/edition) under the MIT Licence.

See [LICENSE](https://github.com/cariad/edition/blob/main/LICENSE) for more information.

### Author

Hello! 👋 I'm **Cariad Eccleston** and I'm a freelance DevOps and backend engineer. My contact details are available on my personal wiki at [cariad.earth](https://cariad.earth).

Please consider supporting my open source projects by [sponsoring me on GitHub](https://github.com/sponsors/cariad/).

### Acknowledgements

- The beautiful [Dracula for Pygments theme](https://github.com/dracula/pygments) is copyright of Dracula Theme and used under the MIT licence.
- Epic thanks to John Gruber for releasing the [Markdown specification](https://daringfireball.net/projects/markdown/).
- Code injection is performed by [dinject](https://github.com/cariad/dinject), copyright of Cariad Eccleston and used under the MIT licence.


