Add interim documentation

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.

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
+Release under the GNU Affero General Public License v3.0 or later (SPDX_
-for details.
+license identifier `AGPL-3.0-or-later`). Refer to the LICENSE_ file for
+details.
 
+
+.. ----------------------------------------------------------------------------
+.. _HACKING: HACKING.rst
 .. _LICENSE: LICENSE
+.. _SPDX: https://spdx.dev/

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)