1 unstable release
0.5.4 | Jul 14, 2022 |
---|
#8 in #blog-post
64KB
1.5K
SLoC
crosspub
A tool for users on tilde servers to cross publish blog posts to HTML and Gemini.
Installation
Run
make
sudo make install
Usage
crosspub is designed to not need any configuration out of the box. To start create a containing directory and initialize it.
mkdir website
crosspub --init
This creates two directories, one for posts
(blogs and articles written on a
specific day) and one for topics
(evolving documents that change and grow over
time), as well as creating a default config file.
crosspub content is written in
gemtext, a lightweight
markup language. Files should end in .gmi
.
Next, change the settings in your config.toml, see Basic Configuration.
Create posts directories in your HTML and Gemini root directories
mkdir ~/public_html/posts
mkdir ~/public_gemini/posts
Change these paths to match your configuration.
When you're ready to generate your website just navigate to the directory you initialized and run
crosspub
Posts syntax
All gemtext files in posts/ must start with a mandatory TOML frontmatter
---
title = "Example Title"
date = "YYYY-MM-DD"
slug = "example"
---
Content goes here
...
The "slug" is a small string that becomes part of the filename, basically a shortened title.
Topics syntax
Files in topics/ start with a slightly different frontmatter that lacks a date field.
---
title = "Example Topic"
slug = "example_topic"
---
...
Basic Configuration
The config file is located at $HOME/crosspub/config.toml
name
is the title of your siteurl
is the base URL of the site (not including the tilde part)username
is your username, your tilde extension on the site minus the~
characterhtml_root
andgemini_root
are the paths to your public_html and public_gemini files.
About files
crosspub allows you to write a bio and have it generate an About page. First make sure you have a directory for crosspub data:
mkdir -p ~/.local/share/crosspub
Next create a file in that directory called about.gmi
. This is just a plain
gemtext file, no frontmatter.
Finally edit ~/.config/crosspub/config.toml
so that use_about_page = true
Advanced Configuration
Custom Templates
If desired, more unique sites can be created by utilizing custom templates. First create the proper directories
mkdir -p ~/.local/share/crosspub/templates/html
mkdir -p ~/.local/share/crosspub/templates/gemini
The default templates are located at /usr/share/crosspub/templates/
. It is
recommended to look at the built-in templates for an explanation of how they
work.
crosspub uses 5 templates each for HTML and Gemini
- index
- post
- topic
- postlist
- about
Some or all of these templates can be shadowed by ones located in
~/.local/share/crosspub/templates
.
Custom CSS
Similar to the templates, site-wide CSS can be modified. User CSS should go in
~/.local/share/crosspub/templates/html/style.css
Post Listing
The default index.html and index.gmi templates both list posts on the homepage.
If you'd like to move this listing to a separate page set post_list = true
in
your config. This creates a listing at {HTML_ROOT}/posts/posts.html
and
{GEMINI_ROOT}/posts/posts.gmi
. crosspub will NOT automatically link to these
listings, so it's up to you to modify other templates as necessary.
Dependencies
~3.5–4.5MB
~85K SLoC