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.

#Setup

1. Log into your server.

2. Clone the Didact repository with Git: git clone https://git.sr.ht/~yujiri/didact.

3. 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:

   • The Crystal compiler, and its package manager, Shards
   • Nginx, the outward-facing web server
   • entr, a command-line tool used by Didact's monitor.sh script 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.

4. Copy the example content from example/ to content/.

5. Compile Didact:

   1. Be in the repository root.
   2. Run shards --production to install Crystal dependencies.
   3. Run ./build.sh. This may take a minute. Note that you need to re-run this script after changing any template files.

6. Copy didact.yml.example to didact.yml and fill out the settings for your site.

7. Generate and install Nginx config file and RSS feed by running src/install.cr.

8. Make sure /var/didact exists and can be read by Nginx. This is where it will serve from.

9. Start the nginx service.

#Adding content

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 .md or .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 .md or .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 TITLE.

• 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 default, so 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.md or 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 ./publish content/article.md.

The included 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 monitor.sh.

Files in your content folder that start with . or _ will not be written to /var/didact unless named explicitly on the command line.