freyjagp/blag
1
0
Fork 0
forked from github.com/blag
Code Actions Packages Releases Activity

replaced sphinx with mkdocs

Browse Source
This commit is contained in:
Bastian Venthur
2023-06-16 11:53:17 +02:00
parent 76b06b31f9
commit b90a54d094
20 changed files with 294 additions and 501 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/CHANGELOG.md Symbolic link
View File

@@ -0,0 +1 @@
/home/venthur/git/blag/CHANGELOG.md

20
docs/Makefile
View File

@@ -1,20 +0,0 @@
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

1
docs/README.md Symbolic link
View File

@@ -0,0 +1 @@
/home/venthur/git/blag/README.md

4
docs/api.md
View File

@@ -1,3 +1,7 @@
# API
::: blag
::: blag.version
::: blag.blag

12
docs/api.rst
View File

@@ -1,12 +0,0 @@
API
===
.. autosummary::
:toctree: api
blag.__init__
blag.version
blag.blag
blag.markdown
blag.devserver
blag.quickstart

1
docs/blag.md Normal file
View File

@@ -0,0 +1 @@
::: blag.blag

282
docs/blag.rst
View File

@@ -1,282 +0,0 @@
Manual
======
Quickstart
----------
Install blag from PyPI_
.. code-block:: sh
$ pip install blag
.. _pypi: https://pypi.org/project/blag/
Run blag's quickstart command to create the configuration, templates and some
initial content.
.. code-block:: sh
$ blag quickstart
Create some content
.. code-block:: sh
$ edit content/hello-world.md
Generate the website
.. code-block:: sh
$ blag build
By default, blag will search for content in ``content`` and the output will be
generated in ``build``. All markdown files in ``content`` will be converted to
html, all other files (i.e. static files) will be copied over).
If you want more separation between the static files and the markdown content,
you can put all static files into the ``static`` directory. Blag will copy
them over to the ``build`` directory.
If you want to customize the look of the generated site, visit the ``template``
directory. It contains jinja2 templates and can be modified as needed.
Those directories can be changed via command line arguments. See
.. code-block:: sh
$ blag --help
Manual
------
Pages and Articles
^^^^^^^^^^^^^^^^^^
Internally, blag differentiates between **pages** and **articles**.
Intuitively, pages are simple pages and articles are blog posts. The decision
whether a document is a page or an article is made depending on the presence
of the ``date`` metadata element: Any document that contains the ``date``
metadata element is an article, everything else a page.
This differentiation has consequences:
* blag uses different templates: ``page.html`` and ``article.html``
* only articles are collected in the Atom feed
* only articles are aggregated in the tag pages
blag does **not** enforce a certain directory structure for pages and
articles. You can mix and match them freely or structure them in different
directories. blag will mirror the structure found in the ``content`` directory
::
content/
article1.md
article2.md
page1.md
results in:
::
build/
article1.html
article2.html
page1.html
Arbitrary complex structures are possible too:
::
content/
posts/
2020/
2020-01-01-foo.md
2020-02-01-foo.md
pages/
foo.md
bar.md
results in:
::
build/
posts/
2020/
2020-01-01-foo.html
2020-02-01-foo.html
pages/
foo.html
bar.html
Static Files
^^^^^^^^^^^^
Static files can be put into the ``content`` directory and will be copied over
to the ``build`` directory as well. If you want better separation between
content and static files, you can use the ``static`` directory and put the
files there. All files and directories found in the ``static`` directory will
be copied over to ``build``.
::
content/
foo.md
bar.md
kitty.jpg
results in:
::
build/
foo.html
bar.html
kitty.jpg
Alternatively:
::
content/
foo.md
bar.md
static/
kitty.jpg
results in:
::
build/
foo.html
bar.html
kitty.jpg
Internal Links
--------------
In contrast to most other static blog generators, blag will automatically
convert **relative** markdown links. That means you can link you content using
relative markdown links and blag will convert them to html automatically. The
advantage is that your content tree in markdown is consistent and
self-contained even if you don't generate html from it.
.. code-block:: markdown
[...]
this is a [link](foo.md) to an internal page foo.
becomes
.. code-block:: html
<p>this is a <a href="foo.html">link</a> to an internal page foo.</p>
Templating
----------
Templates are stored by default in the ``templates`` directory.
============ ====================================== ===================
Template Used For Variables
============ ====================================== ===================
page.html pages (i.e. non-articles) site, content, meta
article.html articles (i.e. blog posts) site, content, meta
index.html landing page of the blog site, archive
archive.html archive page of the blog site, archive
tags.html list of tags site, tags
tag.html archive of Articles with a certain tag site, archive, tag
============ ====================================== ===================
If you make use of Jinja2's template inheritance, you can of course have more
template files in the ``templates`` directory.
``site``
This dictionary contains the site configuration, namely: ``base_url``,
``title``, ``description`` and ``author``. Don't confuse the site-title
and -description with the title and description of individual pages or
articles.
``content``
HTML, converted from markdown.
``meta``
``meta`` stands for all metadata elements available in the article or
page. Please be aware that those are not wrapped in a dictionary, but
**directly** available as variables.
``archive``
A list of ``[destination path, context]`` tuples, where the context are
the respective variables that would be provided to the individual page or
article.
``tags``
List of tags.
``tag``
A tag.
Metadata
---------
blag supports metadata elements in the markdown files. They must come before
the content and should be separated from the content with a blank line:
.. code-block:: markdown
title: foo
date: 2020-02-02
tags: this, is, a, test
description: some subtitle
this is my content.
[...]
blag supports *arbitrary* metadata in your documents, and you can use them
freely in you templates. However, some metadata elements are treated special:
``date``
If a document contains the ``date`` element, it is treated as an
**article**, otherwise as a **page**. Additionally, ``date`` elements are
expected to be in ISO format (e.g. ``1980-05-05 21:58``). They are
automatically converted into ``datetime`` objects with the local timezone
attached.
``tags``
Tags are interpreted as a comma separated list. All elements are stripped
and converted to lower-case: ``tags: foo, Foo Bar, BAZ`` becomes: ``[foo,
foo bar, baz]``.
Tags in **articles** are also used to generate the tag-pages, that
aggregate all articles per tag.
``title`` and ``description``
The title and description are used in the html header and in the atom
feed.
Devserver
---------
blag provides a devserver which you can use for local web-development. The
devserver provides a simple web server, serving your site in
http://localhost:8000 and will automatically rebuild the project when it
detects modifications in one of the ``content``, ``static`` and ``templates``
directories.
.. code-block:: sh
$ blag serve

1
docs/blag_.md Normal file
View File

@@ -0,0 +1 @@
::: blag

69
docs/conf.py
View File

@@ -1,69 +0,0 @@
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
import blag
# -- Project information -----------------------------------------------------
project = 'blag'
copyright = '2021, Bastian Venthur'
author = 'Bastian Venthur'
# The full version, including alpha/beta/rc tags
release = blag.__VERSION__
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autosummary',
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
autodoc_default_options = {
'members': True,
'undoc-members': True,
'private-members': True,
'special-members': True,
}
autosummary_generate = True

1
docs/devserver.md Normal file
View File

@@ -0,0 +1 @@
::: blag.devserver

17
docs/index.md
View File

@@ -1,17 +0,0 @@
# Welcome to MkDocs
For full documentation visit [mkdocs.org](https://www.mkdocs.org).
## Commands
* `mkdocs new [dir-name]` - Create a new project.
* `mkdocs serve` - Start the live-reloading docs server.
* `mkdocs build` - Build the documentation site.
* `mkdocs -h` - Print help message and exit.
## Project layout
mkdocs.yml # The configuration file.
docs/
index.md # The documentation homepage.
... # Other markdown pages, images and other files.

53
docs/index.rst
View File

@@ -1,53 +0,0 @@
.. blag documentation master file, created by
sphinx-quickstart on Sun Mar 21 13:39:00 2021.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to blag!
================
blag is a blog-aware, static site generator, written in Python_. An example
"deployment" can be found here_.
blag is named after the blag of the webcomic xkcd_.
.. _python: https://python.org
.. _xkcd: https://blog.xkcd.com
.. _here: https://venthur.de
Features
--------
* Write content in Markdown_
* Theming support using Jinja2_ templates
* Generation of Atom feeds for blog content
* Fenced code blocks and syntax highlighting using Pygments_
* Integrated devserver
* Available on PyPI_
blag runs on Linux, Mac and Windows and requires Python >= 3.8
.. _markdown: https://daringfireball.net/projects/markdown/
.. _jinja2: https://palletsprojects.com/p/jinja/
.. _pygments: https://pygments.org/
.. _pypi: https://pypi.org/project/blag/
Documentation
=============
.. toctree::
:maxdepth: 2
:caption: Contents:
blag.rst
api.rst
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

35
docs/make.bat
View File

@@ -1,35 +0,0 @@
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=.
set BUILDDIR=_build
if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
:end
popd

264
docs/manual.md Normal file
View File

@@ -0,0 +1,264 @@
# Manual
## Quickstart
Install blag from [PyPI][]
```sh
$ pip install blag
```
[pypi]: https://pypi.org/project/blag/
Run blag's quickstart command to create the configuration, templates and some
initial content.
```sh
$ blag quickstart
```
Create some content
```sh
$ edit content/hello-world.md
```
Generate the website
```sh
$ blag build
```
By default, blag will search for content in `content` and the output will be
generated in `build`. All markdown files in `content` will be converted to
html, all other files (i.e. static files) will be copied over).
If you want more separation between the static files and the markdown content,
you can put all static files into the `static` directory. Blag will copy them
over to the `build` directory.
If you want to customize the look of the generated site, visit the `template`
directory. It contains jinja2 templates and can be modified as needed.
Those directories can be changed via command line arguments. See
```sh
$ blag --help
```
## Manual
### Pages and Articles
Internally, blag differentiates between **pages** and **articles**.
Intuitively, pages are simple pages and articles are blog posts. The decision
whether a document is a page or an article is made depending on the presence of
the `date` metadata element: Any document that contains the `date` metadata
element is an article, everything else a page.
This differentiation has consequences:
* blag uses different templates: `page.html` and `article.html`
* only articles are collected in the Atom feed
* only articles are aggregated in the tag pages
blag does **not** enforce a certain directory structure for pages and articles.
You can mix and match them freely or structure them in different directories.
blag will mirror the structure found in the `content` directory
```
content/
article1.md
article2.md
page1.md
```
results in:
```
build/
article1.html
article2.html
page1.html
```
Arbitrary complex structures are possible too:
```
content/
posts/
2020/
2020-01-01-foo.md
2020-02-01-foo.md
pages/
foo.md
bar.md
```
results in:
```
build/
posts/
2020/
2020-01-01-foo.html
2020-02-01-foo.html
pages/
foo.html
bar.html
```
### Static Files
Static files can be put into the `content` directory and will be copied over to
the `build` directory as well. If you want better separation between content
and static files, you can use the `static` directory and put the files there.
All files and directories found in the `static` directory will be copied over
to `build`.
```
content/
foo.md
bar.md
kitty.jpg
```
results in:
```
build/
foo.html
bar.html
kitty.jpg
```
Alternatively:
```
content/
foo.md
bar.md
static/
kitty.jpg
```
results in:
```
build/
foo.html
bar.html
kitty.jpg
```
### Internal Links
In contrast to most other static blog generators, blag will automatically
convert **relative** markdown links. That means you can link you content using
relative markdown links and blag will convert them to html automatically. The
advantage is that your content tree in markdown is consistent and
self-contained even if you don't generate html from it.
```markdown
[...]
this is a [link](foo.md) to an internal page foo.
```
becomes
```html
<p>this is a <a href="foo.html">link</a> to an internal page foo.</p>
```
```python
def this_is_a(test):
pass
```
### Templating
Templates are stored by default in the `templates` directory.
Template | Used For | Variables
------------ | -------------------------------------- | -------------------
page.html | pages (i.e. non-articles) | site, content, meta
article.html | articles (i.e. blog posts) | site, content, meta
index.html | landing page of the blog | site, archive
archive.html | archive page of the blog | site, archive
tags.html | list of tags | site, tags
tag.html | archive of Articles with a certain tag | site, archive, tag
If you make use of Jinja2's template inheritance, you can of course have more
template files in the `templates` directory.
#### Variables
* `site`: This dictionary contains the site configuration, namely: `base_url`,
`title`, `description` and `author`. Don't confuse the site-title and
-description with the title and description of individual pages or articles.
* `content`: HTML, converted from markdown.
* `meta`: stands for all metadata elements available in the article or page.
Please be aware that those are not wrapped in a dictionary, but **directly**
available as variables.
* `archive`: A list of `[destination path, context]` tuples, where the context
are the respective variables that would be provided to the individual page or
article.
* `tags`: List of tags.
* `tag`: A tag.
### Metadata
blag supports metadata elements in the markdown files. They must come before
the content and should be separated from the content with a blank line:
```markdown
title: foo
date: 2020-02-02
tags: this, is, a, test
description: some subtitle
this is my content.
[...]
```
blag supports *arbitrary* metadata in your documents, and you can use them
freely in you templates. However, some metadata elements are treated special:
* `date`: If a document contains the `date` element, it is treated as an
**article**, otherwise as a **page**. Additionally, `date` elements are
expected to be in ISO format (e.g. `1980-05-09 21:58`). They are
automatically converted into `datetime` objects with the local timezone
attached.
* `tags`: Tags are interpreted as a comma separated list. All elements are
stripped and converted to lower-case: `tags: foo, Foo Bar, BAZ` becomes:
`[foo, foo bar, baz]`. Tags in **articles** are also used to generate the
tag-pages, that aggregate all articles per tag.
* `title` and `description`: The title and description are used in the html
header and in the atom feed.
## Devserver
blag provides a devserver which you can use for local web-development. The
devserver provides a simple web server, serving your site in
http://localhost:8000 and will automatically rebuild the project when it
detects modifications in one of the `content`, `static` and `templates`
directories.
```sh
$ blag serve
```

1
docs/markdown.md Normal file
View File

@@ -0,0 +1 @@
::: blag.markdown

1
docs/quickstart.md Normal file
View File

@@ -0,0 +1 @@
::: blag.quickstart

1
docs/version.md Normal file
View File

@@ -0,0 +1 @@
::: blag.version