diff --git a/docs/blag.rst b/docs/blag.rst new file mode 100644 index 0000000..2343ec8 --- /dev/null +++ b/docs/blag.rst @@ -0,0 +1,268 @@ +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 needed + +.. code-block:: sh + + $ blag quickstart + +Create some content + +.. code-block:: sh + + $ mkdir content + $ 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 looks of the generated site, create a +``template`` directory and put your jinja2 templates here. + +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 create a ``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 + +

this is a link to an internal page foo.

+ + +Templating +---------- + +Custom templates are **optional** and stored by default in the ``templates`` +directory. blag will search the ``templates`` directory first, and fall back +to blag's default built-in templates. + +============ ====================================== =================== +Template Used For Variables +============ ====================================== =================== +page.html pages (i.e. non-articles) site, content, meta +article.html articles (i.e. blog posts) site, content, meta +archive.html archive- and landing 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. diff --git a/docs/index.rst b/docs/index.rst index 7b99e96..731814f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -42,7 +42,7 @@ Documentation :caption: Contents: - quickstart.rst + blag.rst api.rst Indices and tables diff --git a/docs/quickstart.rst b/docs/quickstart.rst deleted file mode 100644 index 21c8573..0000000 --- a/docs/quickstart.rst +++ /dev/null @@ -1,29 +0,0 @@ -Quickstart -========== - -Install blag from PyPI_:: - - $ pip install blag - -.. _pypi: https://pypi.org/project/blag/ - -Run blag's quickstart command to create the configuration needed:: - - $ blag quickstart - -Create some content:: - - $ mkdir content - $ edit content/hello-world.md - -Generate the website:: - - $ blag build - -By default, blag will search for content in ``content`` and the output will be -generated in ``build``. Those directories can be changed via command line -arguments. See:: - - $ blag --help - -