104 lines
2.1 KiB
Markdown
104 lines
2.1 KiB
Markdown
# mdblog
|
|
|
|
This project provides a minimal blogging platform based on Markdown files.
|
|
|
|
## Installation
|
|
|
|
```shell
|
|
$ python setup.py install
|
|
```
|
|
|
|
## Usage
|
|
|
|
```shell
|
|
# The application will listen on port 8000 and it will
|
|
# serve the current folder
|
|
$ madness
|
|
```
|
|
|
|
```
|
|
usage: madblog [-h] [--host HOST] [--port PORT] [--debug] [path]
|
|
|
|
Serve a Markdown folder as a web blog.
|
|
|
|
The folder should have the following structure:
|
|
|
|
.
|
|
-> markdown
|
|
-> article-1.md
|
|
-> article-2.md
|
|
-> ...
|
|
-> img [recommended]
|
|
-> favicon.ico
|
|
-> icon.png
|
|
-> image-1.png
|
|
-> image-2.png
|
|
-> ...
|
|
-> css [optional]
|
|
-> custom-1.css
|
|
-> custom-2.css
|
|
-> ...
|
|
-> fonts [optional]
|
|
-> custom-1.ttf
|
|
-> custom-1.css
|
|
-> ...
|
|
-> templates [optional]
|
|
-> index.html [for a custom index template]
|
|
-> article.html [for a custom article template]
|
|
|
|
positional arguments:
|
|
path Base path for the blog
|
|
|
|
options:
|
|
-h, --help show this help message and exit
|
|
--host HOST Bind host/address
|
|
--port PORT Bind port (default: 8000)
|
|
--debug Enable debug mode (default: False)
|
|
```
|
|
|
|
## Markdown files
|
|
|
|
Articles are Markdown files stored under `pages`. For an article to be correctly rendered,
|
|
you need to start the Markdown file with the following metadata header:
|
|
|
|
```markdown
|
|
[//]: # (title: Title of the article)
|
|
[//]: # (description: Short description of the content)
|
|
[//]: # (image: /img/some-header-image.png)
|
|
[//]: # (author: Author Name <email@author.me>)
|
|
[//]: # (published: 2022-01-01)
|
|
```
|
|
|
|
## Images
|
|
|
|
Images are stored under `img`. You can reference them in your articles through the following syntax:
|
|
|
|
```markdown
|
|
|
|
```
|
|
|
|
You can also drop your `favicon.ico` under this folder.
|
|
|
|
## LaTeX support
|
|
|
|
LaTeX support is built-in as long as you have the `latex` executable installed on your server.
|
|
|
|
Syntax for inline LaTeX:
|
|
|
|
```markdown
|
|
And we can therefore prove that \( c^2 = a^2 + b^2 \)
|
|
```
|
|
|
|
Syntax for LaTeX expression on a new line:
|
|
|
|
```markdown
|
|
$$
|
|
c^2 = a^2 + b^2
|
|
$$
|
|
```
|
|
|
|
## RSS syndacation
|
|
|
|
RSS feeds for the blog are provided under the `/rss` URL.
|
|
|