Didact is a static site generator with:
Breadcrumb navigation links autogenerated from folder hierarchy
Autogenerate Nginx config and an RSS feed
About 200 lines of code
I consider Didact finished.
Log into your server.
Clone the Didact repository with Git:
git clone https://git.sr.ht/~yujiri/didact.
Install the dependencies. They should be in the repository for any Unix operating system, but the exact names of packages might vary so I can't give exact install instructions. The dependencies are:
monitor.shscript to automatically update files
find, another command-line tool used by
monitor.sh. May be preinstalled, but if not, the package for it is probably called "findutils".
Nginx needs to be set to start at boot time with your system's service manager, but don't actually start it until after step 7.
Copy the example content from
shards --productionto install Crystal dependencies.
./build.sh. This may take a minute. Note that you need to re-run this script after changing any template files.
didact.yml and fill out the settings for your site.
Generate and install Nginx config file and RSS feed by running
/var/didact exists and can be read by Nginx. This is where it will serve from.
Start the nginx service.
Content goes in
content/. The folder is not tracked by git, and the recommended way to use Didact is to store your content in its own repository that you put there.
The page generator script,
generate, will read this folder and populate
/var/didact with the actual files to be served to browsers. Any content file that doesn't end in
.html (images, downloads, etc), is assumed to be a static file, and will be hard-linked directly to the deploy folder. Files that do end in
.html are your main text context.
For text content files, the generator script fills out a template stored in
content/_templates/ using the content file, so you don't have to write boilerplate HTML. A content file consists of a few settings at the top, a blank line, and then the content of the page. The settings understood by the default template are:
TITLE ... - (required) SEO title to be displayed as the title of the browser window and in search results.
NAV ... - The title segment to display in the navbar. Only applies to category index pages. Defaults to the value of
DESC ... - The description to display in contexts like search results and social media link previews.
TEMPLATE ... - says which page template to use (don't include the
.ecr suffix of the template filename). Defaults to
content/_templates/default.ecr will be used.
NOINDEX - include an HTML meta tag that tells search engines not to show the page in search results.
Content files that end in
.md have their content (not the template settings at the top) processed using the Sanemark processor, which allows you to write them in a version of Markdown, a lightweight format for text content that's more convenient than raw HTML. Files that end in
.html are not processed as Markdown.
Content can be organized hierarchically via subfolders in the content folder. Each directory should have an
index.html that acts as the index page for that category or section of your site.
Content templates are written in ECR (Embedded CRystal), so learning some Crystal will help if you wish to customize them.
After finishing a new article, you should add it to your RSS feed (which will cause subscribers to get notified) by running
monitor.sh is meant to run in the background. It monitors
content/ for changes and automatically re-runs
generate as necessary. However, it can only detect changes to existing files, not new files, renames, or removals. So if you change those things, you'll need to restart
Files in your content folder that start with
_ will not be written to
/var/didact unless named explicitly on the command line.