Welcome to AlchemyPub

This page explains in detail how AlchemyPub works and how you can set it up.

On the left, you can see the menu generated from all your files in the priv/pages directory. It consists of three parts:

On the top are Pages
In the middle, Posts are ordered by date
On the bottom, the list of page tags is shown

Menu navigation is handled by Phoenix LiveView patch actions. This means navigating the menu does not trigger a full page reload, it only fetches the new content using websockets and swaps out the relevant parts.

You can set up the page structure as follows.

YAML Frontmatter

Every page can be configured using the YAML frontmatter. Begin the page using:

---
key: value
---

to set properties for each page.

The following properties are available on all pages:

title: This sets the title that is shown in the menu. If the title property does not exist, the content of the first header <h1> on the page is used. If there is no header, it defaults to the file name. Example:
```
---
title: Home
---
```
banner: This sets an image to be shown top of the content. The image file has to reside in the priv/static/images folder. Example:
```
---
banner: Tärnättholmarna.jpg
---
```
tags gives each page a list of tags. Pages can be filtered through the tag list on the bottom of the menu. Example:
```
---
tags:
  - Example
  - Documentation
---
```
deck sets the type of the page to LiveDeck to display interactive presentations.
```
---
deck: true
---
```
hidden hides a page from the menu. It can still be accessed directly, using a link. You can find a hidden page under Secret. Example:
```
---
hidden: true
---
```
nobot hides a page in the menu from webcrawlers that do not handle websocket connections. This is done by filtering it during the inital page delivery. When a browser connects through the websocket, it will show up immediately to the user. The page can still be accessed directly, using a link. Be aware, that by linking the page, it will be picked up by bots again. You can find such a page under Imprint. Example:
```
---
nobot: true
---
```

Pages

Pages live in the root of the menu. Their order is manually defined using the rank property. The page with the lowest rank automatically becomes the home page accessible from the root path / of the page. Example:

---
rank: 0
---

Icons

Pages can be given an icon using the icon property. Example:

---
icon: home-modern
---

It uses the Heroicons library. To make sure your icons are added to the compiled tailwind output, you have to add it to the module.exports.safelist in assets/tailwind.config.js. It is possible to whitelist all icons using a pattern, however this adds around 1MB to the generated CSS.

Posts

All files that do not have a rank property automatically become Posts. Posts are sorted by date on the menu, grouped by their year.

The date of a file can be specified using the date property in the frontmatter. Dates are specified using a YYYY-MM-DD string. Example:

---
date: 1845-01-29
---

If no date is set in the frontmatter, it will default to the modification date of the file. This allows you to drop new files in the pages folder without frontmatter, and they will still be ordered reasonably. Be aware that if you change a file, the date will also change. To keep the date of posts fixed, please use the date property.

LiveDeck: Interactive Presentations

Setting the option deck: true in the YAML frontmatter will turn a page into a presentation. For more information on presentations, see LiveDeck.

For all files, a url will be generated from its filename to link to the file. Spaces and special characters will be stripped out, and links will work case insensitive. Pages are referenced by name only. Posts will always use the date and name in the path.

Additionally, posts can also be accessed only by their date. The title is only required if multiple posts share the same date. If only the title or the date is given or either one is incorrect, the post will still be found. This allows links to posts to be more stable if either the date or the title is changed later.

The following links all reference the same page:

Syntax highlighting

Code blocks get highlighted on the client using hljs. To configure supported languages, add them to your assets/js/app.js. YAML, JavaScript (to render the documentation) and of course Elixir are supported by default. Example:

hljs.registerLanguage("elixir", require("highlight.js/lib/languages/elixir"));

A list of all supported languages can be found here.

Analytics

In the dev environment, the analytics dashboard can be accessed under /dev/dashboard/analytics. To allow access in production, make sure the access to the analytics page is secured (if you don't want it to be public). This can be set up in the lib/alchemy_pub/router.ex in the scope "/dev" block or by setting the environment variables AUTH_USERNAME and AUTH_PASSWORD for basic auth on the dashboard. Visiting the analytics page will also set an admin cookie, so you can take

Welcome to AlchemyPub

Menu #

YAML Frontmatter #

Pages #

Icons #

Posts #

LiveDeck: Interactive Presentations #

Links & Navigation #

Syntax highlighting #

Analytics #

Menu