https://github.com/criccomini/markupdown
A static site generator toolkit written in Python
https://github.com/criccomini/markupdown
blog-engine liquid-templating-engine markdown python static-site-generator static-website
Last synced: 9 months ago
JSON representation
A static site generator toolkit written in Python
- Host: GitHub
- URL: https://github.com/criccomini/markupdown
- Owner: criccomini
- License: mit
- Created: 2025-02-07T21:02:30.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-02-24T23:37:04.000Z (11 months ago)
- Last Synced: 2025-02-25T00:28:18.596Z (11 months ago)
- Topics: blog-engine, liquid-templating-engine, markdown, python, static-site-generator, static-website
- Language: Python
- Homepage:
- Size: 115 KB
- Stars: 8
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Markupdown
Markupdown is a collection of functions that help you build static sites with [markdown](https://daringfireball.net/projects/markdown/).
Many static site generators are complex, rigid, and rely on plugins for extensibility. Markupdown is the opposite: it's dumb but programmable. It's kind of like a build system for static sites. A typical flow looks like this:
- Stage your `site` directory with markdown, CSS, Javascript, images, and so forth (using `cp`)
- Transform your files to add metadata to the frontmatter (using functions like `title`, `link`, `blurb`, and so on)
- Render the markdown with [Liquid](https://shopify.github.io/liquid/) templates (using `render`)
You can call Markdown's functions any way you like, but I recommend creating a little `build.py` file in your project root:
```python
#!/usr/bin/env python3
from markupdown import *
# Copy files to the site directory
cp("assets/**/*.*", "site")
cp("content/**/*.md", "site")
# Update markdown frontmatter
title("site/**/*.md")
link("site/**/*.md")
blurb("site/**/*.md")
siblings("site/**/index.md")
children("site/**/index.md")
changelog("content/**/*.md", "site")
sitemap("site/**/*.md", site_url="http://example.com")
# Render site
render("site/**/*.md", site={"title": "My Site"})
# Minify site HTML, CSS, and JS
minify("site/**/*.html")
minify("site/**/*.css")
minify("site/**/*.js")
```
## Functions
Markupdown ships with the following functions:
- `blurb`: Updates the `blurb` field in markdown frontmatter to include a brief summary
- `changelog`: Updates the `created_at`, `updated_at`, and `change_log` fields in markdown frontmatter
- `children`: Generates `children` frontmatter for child directories with index.md files
- `clean`: Deletes the `site` directory
- `cp`: Copies files to the site directory
- `feed`: Generates RSS and Atom feeds
- `init`: Initializes a directory with an example site
- `link`: Updates the `link` field in markdown frontmatter with the relative URL path
- `minify`: Minifies HTML, CSS, and JS
- `references`: Parses markdown for hrefs and generates `references` and `backreferences` frontmatter for markdown files
- `render`: Renders markdown using Liquid templates
- `serve`: Starts a local HTTP server with live reload to view the site
- `siblings`: Generates `siblings` frontmatter that contains paths for sibling markdown files
- `sitemap`: Generates an XML sitemap
- `title`: Updates the `title` field frontmatter with the value of the first # h1 or filename
- `toc`: Generates a table of contents from markdown files
- `transform`: Applies a transformation function to the frontmatter in markdown files
See [DOCUMENTATION.md](./DOCUMENTATION.md) for more information.
## Installation
```bash
pip install markupdown
```
Markupdown is compatible with Python 3.10 to 3.12
## Usage
After you install Markupdown, go to an empty directory and initialize it:
```bash
python -m markupdown init
```
This will create a scaffolding with files and directories like this:
```text
.
├── assets
│ ├── css
│ │ └── style.css
│ ├── images
│ └── js
├── content
│ ├── index.md
│ └── posts
│ ├── index.md
│ ├── post1.md
│ └── post2.md
├── templates
│ ├── _footer_.liquid
│ ├── _head_.liquid
│ ├── _header_.liquid
│ ├── _pages_.liquid
│ └── default.liquid
├── .gitignore
└── build.py
```
Run `./build.py` to generate your site. The output will be in the `site` directory.
Markupdown comes with a server you can start with:
```bash
python -m markupdown serve
```
Open [http://localhost:8000](http://localhost:8000). You should see your new site.
You can clean your `site` directory with:
```bash
python -m markupdown clean
```