texiblog/README

texiblog: a static website generator based on Texinfo

This is the README file for texiblog, a static website generator based
on Texinfo.

  Copyright 2023 Frederico Muñoz

  Copying and distribution of this file, with or without modification,
  are permitted in any medium without royalty provided the copyright
  notice and this notice are preserved.

Home page: https://interlaye.red/Texiblog.html
Primary distribution point: https://notabug.org/fsm/texiblog

Texiblog is a static site generator that targets personal websites and
blogs, using `texi2any' for most its functionality -- using just
`texi2any' is perfectly possible, so start there if you don't think
you need anyting more, give it a try!

Texiblog requires GNU Texinfo to work; it specifically requires
`texi2any', so in theory only that file (and dependencies, like Perl)
is needed for the primary use case of creating HTML, but there are
other build targets that create an Info file or a PDF that depend on
other components that are usually installed as Texinfo dependencies;
GNU Texinfo is located at https://www.gnu.org/software/texinfo/ .

Texiblog adds some features to make it easier to use for the intended
purpose:

- Makefile based workflow: all steps are done through the Makefile
- Costumisation through GNU m4
- CSS to make it easier to read on large screens
- Automatic creation of Atom and RSS feeds
- Automatic post descriptions and dates views (using Texinfo menus)
- Some Texinfo macros to simplify writing
- Post-processing to enhance the navigation bar

HOW TO USE IT

The first step is changing `./src/config.m4' to specify the main
variables (website title, author name, etc). Doing a `make' will
create the static website in `./out' , and it can be previewed by
looking at `./out/index.html'.

Change `src/index.texi' to fit your needs, which can mean removing the
link to `./src/about.texi' or anything else. Then, add other sections
to it for the "static" part of the site, or add files under src/posts/
to add articles that will appear under the Posts section, organised by
year.

The files that will typically need some change are (under `./src'):

- config.m4: as described above, this is the main configuration file
- index.texi: the index of the site, will include other Texinfo files.
- about.texi: an example "About" section
- concepts.texi: to add a Concepts Index (similar to an index of tags)

For the blog side of things:

- posts/ : the directory under which Texinfo files are added, used as
  blog posts.
- posts/2023-08-25-Timeline.texi: an example of a blog post; note that
  the filename should start with the timestamp in ISO format to
  simplify ordering.

The following shouldn't require changes, unless to enhance things in
different ways (that is to say, they can be kept unchanged to get the
features that exist by default):

- posts.m4, posts.texi: used for automatic creation of the posts menu,
  which provides a view with the date (sorted by recent). `posts.texi'
  is automatically created from the `m4' file.
- config.texi.m4, config.texi: these incorporate the variables defined
  in `config.m4' in a Texinfo file that is imported by
  `index.texi'. It also includes the last updated post.
- macros.texi: the `@date' macro used for blog posts, and others that
  simplify things like @imagec (add image, in float, with caption).

The following files are used in creating the Atom and RSS feeds:

- atom.m4
- rss.m4

There is a `src/lib' directory which is where `m4' auxiliary files are
kept.

SOME NOTES ON POSTS

A post is a Texinfo file under `./src/posts', which is automatically
included in the Posts table, and potentially has a link in the home
header if it's the latest one (this can be removed from
`index.texi'). Currently, the following is required:

- The name of the file should begin with the date in YYYY-MM-DD format.
- The file must start with:
  @node <shortname>: required to make it a separate page, must be unique.
  @section <title>: the title of the post
  @date <date>: the date of the post, in YYYY-MM-DD format


There is some redundancy in the filename and @date requirement that
will be removed in a next version.

**Note**: the current version works with Texinfo 7.0.3; it might work
with other, older versions, but it's not guaranteed. Texinfo 7.1
changes the way menus are handled (and apparently also the order in
which `@include` is processed), which affects the way the posts menu
work. A quick  workaround is to change the `FORMAT_MENU=menu` to
`FORMAT_MENU=sectiontoc`, which works but doesn't show the date in the
post listing.