• This repository has been archived on 02/Sep/2021
  • Stars
    star
    307
  • Rank 136,109 (Top 3 %)
  • Language
    Python
  • License
    MIT License
  • Created over 14 years ago
  • Updated about 3 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Preprocessor for Markdown files to generate a table of contents and other documentation needs

Markdown Preprocessor (MarkdownPP)

NOTICE: This project is no longer actively maintained. It will not receive any future releases.

The Markdown Preprocessor is a Python module designed to add extended features on top of the excellent Markdown syntax defined by John Gruber. These additions are mainly focused on creating larger technical documents without needing to use something as heavy and syntactically complex as Docbook.

MarkdownPP uses a set of selectable modules to apply a series of transforms to the original document, with the end goal of generating a new Markdown document that contains sections or features that would be laborious to generate or maintain by hand.

Documents designed to be preprocessed by MarkdownPP should try to follow the convention of naming files with a .mdpp extension, so that MarkdownPP can generate a document with the same name, but with the standard .md extension. As an example, this document in raw format is named "readme.mdpp", and the generated document from MarkdownPP is named "readme.md" so that GitHub can find and process that document when viewing the repository.

Build Status

1. Installation and Usage
2. Modules
2.1. Includes
2.2. IncludeURLs
2.3. IncludeCode
2.4. Table of Contents
2.5. Reference
2.6. LaTeX Rendering
2.7. YouTube Embeds
3. Examples
4. Support
5. References

1. Installation and Usage

Currently, you'll need to download the source code from GitHub or clone the repository, and the run the installation script manually.

pip install MarkdownPP

There are two components to the project: a Python module, MarkdownPP, and a Python script that acts as a simple command line interface to the module, markdown-pp.

Assuming you have a file named foo.mdpp, you can generate the preprocessed file foo.md by running the following command:

$ markdown-pp foo.mdpp -o foo.md

If you do not specify an output file name, the results will be printed to stdout, enabling them to be piped to another command.

By default, all available modules are enabled. You can specify a list of modules to exclude:

$ markdown-pp foo.mdpp -o foo.md -e latexrender,youtubembed

To see usage instructions, including a list of enabled modules, supply the -h or --help arguments:

$ markdown-pp --help

2. Modules

2.1. Includes

In order to facilitate large documentation projects, MarkdownPP has an Include module that will replace a line of the form !INCLUDE "path/to/filename" with the contents of that file, recursively including other files as needed.

File foo.mdpp:

Hello

File bar.mdpp:

World!

File index.mdpp:

!INCLUDE "foo.mdpp"
!INCLUDE "bar.mdpp"

Compiling index.mdpp with the Include module will produce the following:

Hello
World!

Furthermore, the Include module supports the shifting of headers in the file to be included. For example,

File foo.mdpp:

# Foo
## Bar

File index.mdpp:

# Title
## Subtitle
!INCLUDE "foo.mdpp", 2

Compiling index.mdpp with the Include module and using 2 as shift parameter will yield:

# Title
## Subtitle
### Foo
#### Bar

2.2. IncludeURLs

Facilitates the inclusion of remote files, such as files kept in a subversion or GitHub repository. Like Include, the IncludeURL module can replace a line of the form !INCLUDEURL "http://your.domain/path/to/filename" with the contents returned from that url, recursively including additional remote urls as needed.

IncludeURL runs immediately after the Include module finishes executing. This means that is it possible to include local files that then require remote files, but impossible parse !INCLUDE statements found in remote files. This is prevent ambiguity as to where the file would be located.

Remote file http://your.domain/foo.mdpp:

Hello

Remote file http://your.domain/bar.mdpp:

Remote World!

Local file index.mdpp:

!INCLUDEURL "http://your.domain/foo.mdpp"
!INCLUDEURL "http://your.domain/bar.mdpp"

Compiling index.mdpp with the IncludeURL module will produce the following:

Hello
Remote World!

2.3. IncludeCode

Facilitates the inclusion of local code files. GFM fences will be added around the included code.

Local code file hello.py:

def main():
    print "Hello World"


if __name__ == '__main__':
    main()

Local file index.mdpp:

# My Code

!INCLUDECODE "hello.py"
Easy as that!

Compiling index.mdpp with IncludeCode module wil produce the following:

# My Code

```
def main():
    print "Hello World"


if __name__ == '__main__':
    main()
```
Easy as that!

Furthermore the IncludeCode module supports line extraction and language specification. The line extraction is like python list slicing (e.g. 3:6; lines three to six). Please note that line counting starts at one, not at zero.

Local file index.mdpp:

# My Code

!INCLUDECODE "hello.py" (python), 1:2
Easy as that!

Compiling index.mdpp with IncludeCode module will produce the following:

# My Code

```python
def main():
    print "Hello World"
```
Easy as that!

2.4. Table of Contents

The biggest feature provided by MarkdownPP is the generation of a table of contents for a document, with each item linked to the appropriate section of the markup. The table is inserted into the document wherever the preprocessor finds !TOC at the beginning of a line. Named <a> tags are inserted above each Markdown header, and the headings are numbered hierarchically based on the heading tag that Markdown would generate.

2.5. Reference

Similarly, MarkdownPP can generate a list of references that follow Markdown's alternate link syntax, eg [name]: <url> "Title". A list of links will be inserted wherever the preprocessor finds a line beginning with !REF. The generated reference list follows the same alternate linking method to ensure consistency in your document, but the link need not be referenced anywhere in the document to be included in the list.

2.6. LaTeX Rendering

Lines and blocks of lines beginning and ending with $ are rendered as LaTeX, using QuickLaTeX.

For example,

$\displaystyle \int x^2 = \frac{x^3}{3} + C$

becomes

\displaystyle \int x^2 = \frac{x^3}{3} + C

2.7. YouTube Embeds

As GitHub-flavored Markdown does not allow embed tags, each line of the form !VIDEO "[youtube url]" is converted into a screenshot that links to the video, roughly simulating the look of an embedded video player.

For example,

!VIDEO "http://www.youtube.com/embed/7aEYoP5-duY"

becomes

Link to Youtube video

3. Examples

Example file.mdpp:

# Document Title

!TOC

## Header 1
### Header 1.a
## Header 2

!REF

[github]: http://github.com "GitHub"

The preprocessor would generate the following Markdown-ready document file.md:

# Document Title

1\. [Header 1](#header1)
1.1\. [Header 1.a](#header1a)
2\. [Header 2](#header2)

<a name="header1"></a>
## Header 1
<a name="header1a"></a>
### Header 1.a
<a name="header2"></a>
## Header 2

*	[GitHub][github]

[github]: http://github.com "GitHub"

4. Support

While the project should work on most recent versions of Python, this project is no longer supported.

5. References

More Repositories

1

znc-push

Push notification service module for ZNC
C++
556
star
2

spotify-gnome

Gnome media key integration for the Spotify Linux client
Python
183
star
3

zsh-titles

Terminal/tmux titles based on current location and task
Shell
56
star
4

multiprocessing-keyboardinterrupt

Python
48
star
5

pycon

Python conference talks
Python
47
star
6

fissix

backport of lib2to3, with enhancements
Python
45
star
7

arch

Personal package repository for Arch Linux
Shell
28
star
8

nib

static site generator with content pipeline
Python
19
star
9

pianobar-python

Python wrapper and Gnome integration for the Pandora client "pianobar"
Python
16
star
10

dotlink

Python script to automate deployment of dotfile from git repos to local and remote hosts
Python
16
star
11

ruff-api

Experimental Python API for Ruff
Python
15
star
12

tasky

Python asyncio framework for task-based execution
Python
14
star
13

zsh-opt-path

Automatically add ~/opt/*/bin to $PATH
Shell
13
star
14

libseinfeld

Python library for querying Seinfeld quotes
Python
9
star
15

gifpaper

Android live wallpaper using gifs
Java
7
star
16

ent

Python library for creating arbitrary data structs
Python
5
star
17

robattery

Battery monitoring background service for Android devices
Java
5
star
18

digital-ocean-dns

Sync DNS zones from YAML to Digital Ocean domains API
Python
4
star
19

aioseinfeld

What's the deal with asyncio?
Python
4
star
20

unittest-ft

Run Python tests in parallel with free threading
Python
4
star
21

congress

Search engine passthrough with customizable shortcuts
Python
3
star
22

zsh-which

Run `which` on the command currently in the zsh buffer
Shell
3
star
23

aioslack

AsyncIO Slack Library
Python
3
star
24

flaskstrap

Simple bootstrapped python framework on top of flask
Python
3
star
25

snailspace

Snail's Pace, 2D game project developed at RIT
C#
3
star
26

resume

RΓ©sumΓ©
TeX
3
star
27

apigen-ci

API Generator for CodeIgniter with support for multiple data formats
PHP
3
star
28

seinfeld

Seinfeld quote application
Python
3
star
29

plinky

Simple link site
Python
3
star
30

jaymap

JMAP client for asyncio
Python
3
star
31

rst2pyi

Convert reStructuredText annotations to PEP 484 type stubs
Python
3
star
32

pyranha

Elegant IRC client written in Python
Python
3
star
33

libcst.space

Interactive playground for LibCST
HTML
3
star
34

zsh-take

zsh plugin replicating `take` from ohmyzsh
Shell
3
star
35

zsh-pyenv

Automatic initialization of pyenv when available
Shell
2
star
36

homebrew-formula

Custom homebrew formulae
Ruby
2
star
37

noswap

Less
2
star
38

supybot-plugins

Custom plugins for Supybot
Python
2
star
39

znc-notifo

Legacy ZNC to Notifo module. No longer maintained. Visit https://github.com/jreese/znc-notify for new releases.
C++
2
star
40

structures

Generic data structure implementations
C++
2
star
41

dotfiles

my public dotfiles
Vim Script
2
star
42

zsh-amethyst

zsh theme
Shell
2
star
43

hang

A program that does nothing to enable a forked, background SSH tunneling session
Makefile
1
star
44

rit

Small class projects from SE courses at RIT
C
1
star
45

equinox

C#
1
star
46

euler

Project Euler implementations
Python
1
star
47

gammadraconis

Gamma Draconis, 3D game created at RIT
C#
1
star
48

apollo

elegant IRC client
JavaScript
1
star
49

oauth-ci

CodeIgniter library for OAuth including Server and Client roles
PHP
1
star
50

click-fuzzy

Fuzzy subcommand matching for click
Python
1
star
51

bitbar-aqi

BitBar plugin for displaying current AQI from one or more nearby PurpleAir sensors
Python
1
star
52

cura-status

Python
1
star
53

systemwatch

cronnable replacement for logwatch, using systemd/journald
Python
1
star
54

nalax

no-nonsense access log analytics
Python
1
star
55

songwhip

simple songwhip client in python
Python
1
star
56

legion

discord bot with quotes, seinfelds, and maybe more
Python
1
star
57

playground

A bunch of random test projects
Python
1
star
58

n7gg

url shortener
Python
1
star
59

cortana

Customized Arch Linux live image builder
Shell
1
star
60

getnib.com

Python
1
star
61

amyreese

readme
1
star
62

edi

slack bot
Python
1
star
63

with-context

Python context managers as decorators
Python
1
star
64

jacks-memoirs

Python
1
star
65

ircstat

IRC channel log statistics
Python
1
star
66

cpgame

Simple game framework for CircuitPython embedded hardware
Python
1
star