this is a link to an internal page foo.
- - -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 - diff --git a/docs/blag_.md b/docs/blag_.md new file mode 100644 index 0000000..317c29f --- /dev/null +++ b/docs/blag_.md @@ -0,0 +1 @@ +::: blag diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 4cb1944..0000000 --- a/docs/conf.py +++ /dev/null @@ -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 diff --git a/docs/devserver.md b/docs/devserver.md new file mode 100644 index 0000000..e62835e --- /dev/null +++ b/docs/devserver.md @@ -0,0 +1 @@ +::: blag.devserver diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 000ea34..0000000 --- a/docs/index.md +++ /dev/null @@ -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. diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 731814f..0000000 --- a/docs/index.rst +++ /dev/null @@ -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` diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 2119f51..0000000 --- a/docs/make.bat +++ /dev/null @@ -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 diff --git a/docs/manual.md b/docs/manual.md new file mode 100644 index 0000000..072e508 --- /dev/null +++ b/docs/manual.md @@ -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 +this is a link to an internal page foo.
+``` + +```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 +``` diff --git a/docs/markdown.md b/docs/markdown.md new file mode 100644 index 0000000..9310fa0 --- /dev/null +++ b/docs/markdown.md @@ -0,0 +1 @@ +::: blag.markdown diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000..a67addd --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1 @@ +::: blag.quickstart diff --git a/docs/version.md b/docs/version.md new file mode 100644 index 0000000..326829d --- /dev/null +++ b/docs/version.md @@ -0,0 +1 @@ +::: blag.version diff --git a/mkdocs.yml b/mkdocs.yml index 0d34f3f..2ad3b2c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,12 +1,22 @@ site_name: blag site_url: https://blag.readthedocs.io/ -nav: - - Home: index.md - - Manual: manual.md - - API: api.md -theme: material repo_url: https://github.com/venthur/blag repo_name: venthur/blag + +nav: + - Home: README.md + - Manual: manual.md + - API: + - blag: blag_.md + - blag.version: version.md + - blag.blag: blag.md + - blag.markdown: markdown.md + - blag.devserver: devserver.md + - blag.quickstart: quickstart.md + - Changelog: CHANGELOG.md + +theme: material + plugins: - search: - mkdocstrings: @@ -14,6 +24,3 @@ plugins: python: options: docstring_style: numpy - allow_inspection: true - show_root_heading: true - show_if_no_docstring: true