Package: edition
📰 EditionWARNING: This is a pre-release project.Editionis 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.HighlightsGetting startedInstallationQuick-start exampleUsageCommand lineCreating your source documentFront matterMarkupCode executionTable of ContentsProjectContributingLicenceAuthorAcknowledgementsHighlightsWrite 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 htmlEmbed your code samples.Edition executes embedded code and injects the results automatically.Getting startedInstallationEdition requiresPython 3.8or later.Install Edition via pip:pipinstalleditionQuick-start exampleCreate this Markdown document asexample-source.md:# Edition exampleSave this file to your local machine as`example-source.md`then run:```basheditionexample-source.mdexample.html--presshtml```Now open`example.html`in a web browser. The code example
below will be complete.```bashpython--version```<!--edition-exec-->Run:editiondocs/example-source.mddocs/example.html--presshtmlPressed: docs/example.htmlFun fact! The code above is executed every time I press this documentation. That gives me confidence that it works and lets you see the actualexample.htmlit generates.UsageCommand lineEdition takes three command line arguments:Source fileDestination file--press htmlto press HTML or--press markdownto press MarkdownCreating your source documentYoursource documentis the Markdown document from which all your editions will be pressed.Any Markdown document you already have -- like your project'sREADME.md-- is already a valid source document, but we can add some front matter and additional markup to help guide the presses.Front matterThe following front matter properties come into play only when pressing HTML.PropertyDescriptionDefaultauthorAuthor nameNo authorfavicon-emojiEmoji to use as faviconNo favicontitlePage titleTop-level headingFor example:---
author: Cariad Eccleston
favicon-emoji: 🍕# If "title" was omitted then the top-level "Example"# heading would be used instead:title: Embedded Example---# ExampleMarkupCode executionTo have Edition execute your code then embed the result:Create a regular Markdown code blockAdd<!--edition-exec-->after the blockFor example:```pythonprint("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 definedCurrently onlybashandpythoncode blocks are supported. More languages can be added if they arerequested.Table of ContentsTo insert a table of contents:<editionvalue="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:<editionvalue="toc"hi="2"/>To exclude any headings below level three:<editionvalue="toc"lo="2"/>ProjectContributingTo contribute a bug report, enhancement or feature request, please raise an issue atgithub.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.LicenceEdition is released atgithub.com/cariad/editionunder the MIT Licence.SeeLICENSEfor more information.AuthorHello! 👋 I'mCariad Ecclestonand I'm a freelance DevOps and backend engineer. My contact details are available on my personal wiki atcariad.earth.Please consider supporting my open source projects bysponsoring me on GitHub.AcknowledgementsThe beautifulDracula for Pygments themeis copyright of Dracula Theme and used under the MIT licence.Epic thanks to John Gruber for releasing theMarkdown specification.Code injection is performed bydinject, copyright of Cariad Eccleston and used under the MIT licence.