From 1aad5808e18e3d80cd0dce1534138c4ee31aed40 Mon Sep 17 00:00:00 2001 From: HiPhish Date: Sun, 11 Sep 2022 22:46:26 +0200 Subject: [PATCH] Add interim documentation --- HACKING.rst | 103 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.rst | 15 +++++++- TODO.rst | 1 + 3 files changed, 117 insertions(+), 2 deletions(-) diff --git a/HACKING.rst b/HACKING.rst index e69de29..b5fa214 100644 --- a/HACKING.rst +++ b/HACKING.rst @@ -0,0 +1,103 @@ +.. default-role:: code + +############################### + Hacking on the HSSG internals +############################### + +This is interim documentation about the project. Eventually it will become a +proper user manual, for now I am using this document to keep notes before they +become lost forever. + + +Project overview +################ + +The idea of HSSG is have a static site generator which acts as a library. Each +website project is its own Common Lisp project that depends on HSSG. It is up +to the website generator how to actually structure and build the website. This +makes it a little harder to set up the website initially, but in return there +are close to no limits as to what kind of website to build. Want a blog? Want +multiple blogs? Multiple languages? Sub-sites? All of that is possible. + +Commonly used features like a blog are provided as plugins. These are not +necessarily actual plugins that hook into HSSG (although they can be), they are +generally additional libraries which also depend on HSSG. Two plugins are +provided as part of this project: the blog plugin and the CommonMark reader +plugin. They are not part of core because they have extra dependencies which +not all users of HSSG might need. + + +Project structure +================= + +All source code is in the `src` directory. HSSG and the plugins each have their +own directory there. + +Each system has a `package.lisp` file which serves as the initial entry point. +This file defines (almost) all systems and packages, but some files may define +small one-off packages which are not used anywhere else + + +Core concepts +############# + +Artifacts +========= + +An artifact is an abstract representation of something that will produce output +when it is written. It can be something like a file that will be copied +verbatim, or a potential HTML page. Artifact can also be of higher order, +meaning they wrap around other artifacts. The compound artifact is a simple +case of just a plain container artifact. On the other hand, the blog artifact +also has its own data such as the blog title. + +Metadata +======== + +Metadata is an association list of key-value pairs. The key is a keyword symbol +which names the kind of data, while the value is whatever. Metadata gets +transformed by templates. + +There are no fixed rules as to what metadata is supposed to represent. Usually +it is information about a web page, but it can also represent a CSS file, or +even something abstract like a product showcase. A product showcase could then +be transformed into metadata representing multiple HTML pages, turning an +abstract domain-specific concept into a more general concept. + +Templates +========= + +A template is a function which transforms metadata to metadata. There are no +further rules, it is the responsibility of the user to chain templates in a +meaningful way. + +There are convenience macros (e.g. `DEFTEMPLATE`) for defining templates and +there are combinator functions which combine templates into other templates +(e.g. `CHAIN-TEMPLATES`). + +Readers +======= + +We have metadata to represent information, we have templates to transform them, +but where do we get metadata from? In theory metadata can come from anywhere, +but in practice it will usually be read from a file. A reader is a function +which takes a path to a file in a certain forma and returns metadata. + +Usually readers will be stored in a key-value variable where the key is the +file format. Another function can then dispatch on the file format to the +correct reader. + + +The blog plugin +############### + +This plugin implements blogging. Each blog is one giant artifact which wraps +around other artifacts. Those other artifacts are private though. + + +The CommonMark reader plugin +############################ + +This plugin provides a reader for CommonMark files. Metadata is given as +key-value pairs before a separator line `---`. Everything after the separator +becomes the content of the file. diff --git a/README.rst b/README.rst index 8de220f..24be4e7 100644 --- a/README.rst +++ b/README.rst @@ -26,10 +26,21 @@ Things will change. Do not use in production unless you are willing to follow find it? Right now I am dogfooding my own product. +Documentation +############# + +See the `HACKING`_ file for a rough overview of the project. + + License ####### -Release under the Affero GNU GPL version 3 or later. Refer to the LICENSE_ file -for details. +Release under the GNU Affero General Public License v3.0 or later (SPDX_ +license identifier `AGPL-3.0-or-later`). Refer to the LICENSE_ file for +details. + +.. ---------------------------------------------------------------------------- +.. _HACKING: HACKING.rst .. _LICENSE: LICENSE +.. _SPDX: https://spdx.dev/ diff --git a/TODO.rst b/TODO.rst index 0e41298..5607852 100644 --- a/TODO.rst +++ b/TODO.rst @@ -25,3 +25,4 @@ Cleanup - How much of each artifact's internals need to be exposed? Make accessor functions? Constructor functions over `MAKE-INSTANCE`? +- Static page metadata without binding (see comment in definition)