# madblog
This project provides a minimal blogging platform based on Markdown files.
## Demos
This project powers the following blogs:
- [Platypush](https://blog.platypush.tech)
- [My personal blog](https://fabiomanganiello.com)
## Installation
```shell
$ python setup.py install
```
## Usage
```shell
# The application will listen on port 8000 and it will
# serve the current folder
$ madblog
```
```
usage: madblog [-h] [--config CONFIG] [--host HOST] [--port PORT] [--debug] [dir]
Serve a Markdown folder as a web blog.
The folder should have the following structure:
.
-> config.yaml [recommended]
-> markdown
-> article-1.md
-> article-2.md
-> ...
-> img [recommended]
-> favicon.ico
-> icon.png
-> image-1.png
-> image-2.png
-> ...
positional arguments:
dir Base path for the blog (default: current directory)
options:
-h, --help show this help message and exit
--config CONFIG Path to a configuration file (default: config.yaml in the blog root directory)
--host HOST Bind host/address
--port PORT Bind port (default: 8000)
--debug Enable debug mode (default: False)
```
## Configuration
The application will look for a `config.yaml` file in the current directory if none was
specified through the `-c` command-line option. The structure is the following:
```yaml
title: Blog title
description: Blog description
link: https://link.to.your.blog
# Use home_link if you have a different home/portal address
# than your blog, otherwise it's the same as `link`
home_link: https://link.to.home
# Path/URL to the logo (default: /img/icon.png)
logo: /path/or/url/here
# Blog language (for the RSS feed)
language: en-US
# Show/hide the header (default: true)
header: true
# Enable/disable the short RSS feed (default: false)
short_feed: false
categories:
- category1
- category2
- category3
```
## Markdown files
Articles are Markdown files stored under `markdown`. 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)
```
If no `markdown` folder exists in the base directory, then the base directory itself will be treated as a root for
Markdown files.
### Folders
You can organize Markdown files in folders. If multiple folders are present, pages on the home will be grouped by
folders.
## 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.
By default, the whole HTML-rendered content of an article is returned under `rss.channel.item.description`.
If you only want to include the short description of an article in the feed, use `/rss?short` instead.
If you want the short feed (i.e. without the fully rendered article as a
description) to be always returned, then you can specify `short_feed=true` in
your configuration.
Raw data
{
"_id": null,
"home_page": "https://git.platypush.tech/blacklight/madblog",
"name": "madblog",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "blog markdown",
"author": "Fabio Manganiello",
"author_email": "info@fabiomanganiello.com",
"download_url": "https://files.pythonhosted.org/packages/83/89/18a827221ec218ca8569b3241ad043785776e8f8314928de184bb717d1e0/madblog-0.2.23.tar.gz",
"platform": null,
"description": "# madblog\n\nThis project provides a minimal blogging platform based on Markdown files.\n\n## Demos\n\nThis project powers the following blogs:\n\n- [Platypush](https://blog.platypush.tech)\n- [My personal blog](https://fabiomanganiello.com)\n\n## Installation\n\n```shell\n$ python setup.py install\n```\n\n## Usage\n\n```shell\n# The application will listen on port 8000 and it will\n# serve the current folder\n$ madblog\n```\n\n```\nusage: madblog [-h] [--config CONFIG] [--host HOST] [--port PORT] [--debug] [dir]\n\nServe a Markdown folder as a web blog.\n\nThe folder should have the following structure:\n\n.\n -> config.yaml [recommended]\n -> markdown\n -> article-1.md\n -> article-2.md\n -> ...\n -> img [recommended]\n -> favicon.ico\n -> icon.png\n -> image-1.png\n -> image-2.png\n -> ...\n\npositional arguments:\n dir Base path for the blog (default: current directory)\n\noptions:\n -h, --help show this help message and exit\n --config CONFIG Path to a configuration file (default: config.yaml in the blog root directory)\n --host HOST Bind host/address\n --port PORT Bind port (default: 8000)\n --debug Enable debug mode (default: False)\n```\n\n## Configuration\n\nThe application will look for a `config.yaml` file in the current directory if none was\nspecified through the `-c` command-line option. The structure is the following:\n\n```yaml\ntitle: Blog title\ndescription: Blog description\nlink: https://link.to.your.blog\n# Use home_link if you have a different home/portal address\n# than your blog, otherwise it's the same as `link`\nhome_link: https://link.to.home\n# Path/URL to the logo (default: /img/icon.png)\nlogo: /path/or/url/here\n# Blog language (for the RSS feed)\nlanguage: en-US\n# Show/hide the header (default: true)\nheader: true\n# Enable/disable the short RSS feed (default: false)\nshort_feed: false\n\ncategories:\n - category1\n - category2\n - category3\n```\n\n## Markdown files\n\nArticles are Markdown files stored under `markdown`. For an article to be correctly rendered,\nyou need to start the Markdown file with the following metadata header:\n\n```markdown\n[//]: # (title: Title of the article)\n[//]: # (description: Short description of the content)\n[//]: # (image: /img/some-header-image.png)\n[//]: # (author: Author Name <email@author.me>)\n[//]: # (published: 2022-01-01)\n```\n\nIf no `markdown` folder exists in the base directory, then the base directory itself will be treated as a root for\nMarkdown files.\n\n### Folders\n\nYou can organize Markdown files in folders. If multiple folders are present, pages on the home will be grouped by\nfolders.\n\n## Images\n\nImages are stored under `img`. You can reference them in your articles through the following syntax:\n\n```markdown\n\n```\n\nYou can also drop your `favicon.ico` under this folder.\n\n## LaTeX support\n\nLaTeX support is built-in as long as you have the `latex` executable installed on your server.\n\nSyntax for inline LaTeX:\n\n```markdown\nAnd we can therefore prove that \\( c^2 = a^2 + b^2 \\)\n```\n\nSyntax for LaTeX expression on a new line:\n\n```markdown\n$$\nc^2 = a^2 + b^2\n$$\n```\n\n## RSS syndacation\n\nRSS feeds for the blog are provided under the `/rss` URL.\n\nBy default, the whole HTML-rendered content of an article is returned under `rss.channel.item.description`.\n\nIf you only want to include the short description of an article in the feed, use `/rss?short` instead.\n\nIf you want the short feed (i.e. without the fully rendered article as a\ndescription) to be always returned, then you can specify `short_feed=true` in\nyour configuration.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A minimal platform for Markdown-based blogs",
"version": "0.2.23",
"project_urls": {
"Homepage": "https://git.platypush.tech/blacklight/madblog"
},
"split_keywords": [
"blog",
"markdown"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "838918a827221ec218ca8569b3241ad043785776e8f8314928de184bb717d1e0",
"md5": "01b253ba81902b00fa94eb178e530da7",
"sha256": "40d81ac6f13a9c9d3291c7523fb39fb422f369f4753a15a7824bd4308618ad92"
},
"downloads": -1,
"filename": "madblog-0.2.23.tar.gz",
"has_sig": false,
"md5_digest": "01b253ba81902b00fa94eb178e530da7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 377086,
"upload_time": "2024-04-10T23:25:45",
"upload_time_iso_8601": "2024-04-10T23:25:45.277975Z",
"url": "https://files.pythonhosted.org/packages/83/89/18a827221ec218ca8569b3241ad043785776e8f8314928de184bb717d1e0/madblog-0.2.23.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-10 23:25:45",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "madblog"
}
JSON