Skip to main content

Creates beautiful HTML and Markdown editions of your documentation

Project description

📰 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.

Highlights

  • Write your documentation once.
    Edition presses README.md and HTML documents ready to upload directly to GitHub Pages or any other static hosting, all from the same source.
  • Works out of the box.
    With one command, Edition converts your existing README.md to beautiful HTML: edition README.md index.html --press html
  • Embed your code samples.
    Edition executes embedded code and injects the results automatically.

Getting started

Installation

Edition requires Python 3.8 or later.

Install Edition via pip:

pip install edition

Quick-start example

Create this Markdown document as example-source.md:

# 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:

edition docs/example-source.md docs/example.html --press html
Pressed: docs/example.html

Fun fact! The code above is executed every time I press this documentation. That gives me confidence that it works and lets you see the actual example.html it generates.

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:

---
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
  2. Add <!--edition-exec--> after the block

For example:

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

<!--edition-exec-->

If your code fails then an error message will be injected:

print(foo)
Traceback (most recent call last):
  File "<string>", line 1, in <module>
NameError: name 'foo' is not defined

Currently only bash and python code blocks are supported. More languages can be added if they are requested.

Table of Contents

To insert a table of contents:

<edition value="toc" />

You can optionally specify "hi" and "lo" values to restrict the table to a range of headings.

For example, to exclude the title and start at second-level headings:

<edition value="toc" hi="2" />

To exclude any headings below level three:

<edition value="toc" lo="2" />

Project

Contributing

To contribute a bug report, enhancement or feature request, please raise an issue at 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 under the MIT Licence.

See 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.

Please consider supporting my open source projects by sponsoring me on GitHub.

Acknowledgements

  • The beautiful Dracula for Pygments theme is copyright of Dracula Theme and used under the MIT licence.
  • Epic thanks to John Gruber for releasing the Markdown specification.
  • Code injection is performed by dinject, copyright of Cariad Eccleston and used under the MIT licence.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

edition-1.0.0a14-py3-none-any.whl (18.7 kB view details)

Uploaded Python 3

File details

Details for the file edition-1.0.0a14-py3-none-any.whl.

File metadata

  • Download URL: edition-1.0.0a14-py3-none-any.whl
  • Upload date:
  • Size: 18.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.6.0 importlib_metadata/4.8.2 pkginfo/1.8.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.10.0

File hashes

Hashes for edition-1.0.0a14-py3-none-any.whl
Algorithm Hash digest
SHA256 0e6b12201b3e6c261b794283cf50c294345f57d4d439a95aef1f3411a660fbd7
MD5 ef7bdee3ea22752c544f8d055fc941a7
BLAKE2b-256 698d5609fdbd2da51351a8cea6ae99df199d9231cc001ff2353de8a55ac2477c

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page