Site Configuration
Listsome is configured via listsome.toml in your site root. Run listsome init to generate a default config, then edit it to match your setup.
Full Example
[site]
name = "My DIY Projects"
url = "https://projects.example.com"
description = "Step-by-step guides for things I built"
language = "en"
author = "Your Name"
about = "https://yourdomain.com/about"
email = "you@example.com"
source_repo = "https://codeberg.org/username/my-projects"
[site.fediverse]
mastodon = "@username@mastodon.social"
[build]
output_dir = "./output"
theme = "default"
drafts = false
parallel_jobs = 8
incremental = true
[webmention]
enabled = true
endpoint = "https://webmention.io/yourdomain.com/webmention"
require_approval = true
notify = false
[dev]
base_url = "http://localhost:8080"
port = 8080
[deploy]
host = "your-server.local"
user = "deploy"
path = "/var/www/site"
[fediverse]
enabled = false
mastodon_instance = "https://mastodon.social"
mastodon_token = ""
auto_syndicate = false
default_hashtags = ["#DIY", "#makers"]
[site]: Site Metadata
| Field | Type | Description |
|---|---|---|
name | string | Site title, shown in header and page titles |
url | string (optional) | Production URL. Used for absolute links in feeds and sitemaps |
description | string | Short site description, shown below the site name in the header |
language | string | Language code for the HTML lang attribute (default: en) |
author | string | Default author name for projects without an explicit author in frontmatter. Also used in the footer copyright |
about | string (optional) | URL to your about page. Sets the u-url on your author h-card for IndieWeb identity verification |
email | string (optional) | Contact email. Shown as a “Reply via email” link on project pages |
source_repo | string (optional) | Repository URL. Enables “Edit This Page” links that point to the source markdown |
Fediverse Handles (under [site.fediverse])
These live under [site.fediverse] and are optional: they enable sharing features on project pages.
| Field | Type | Description |
|---|---|---|
mastodon | string (optional) | Your full Mastodon handle (for example, @username@mastodon.social). Enables a “Share on Mastodon” link on project pages |
pixelfed | string (optional) | Your Pixelfed username (for photo gallery integration) |
peertube | string (optional) | Your PeerTube channel |
bluesky | string (optional) | Your Bluesky handle (secondary) |
[build]: Build Settings
| Field | Type | Default | Description |
|---|---|---|---|
output_dir | string | ./output | Where the generated site is written |
theme | string | default | Theme name (currently unused, single built-in theme) |
drafts | boolean | false | Include projects with status: draft in builds |
parallel_jobs | integer | number of CPU cores | How many projects to build concurrently |
incremental | boolean | true | Skip projects whose source has not changed since last build |
base_url | string (optional) | none | Set this for production deployments where the site lives at a subpath |
[webmention]: Webmention Settings
Webmentions let other sites notify you when they link to your projects. Requires endpoint to be configured.
| Field | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable webmention sending |
endpoint | string | https://webmention.io/yourdomain.com/webmention | Your webmention endpoint (get one at webmention.io) |
require_approval | boolean | true | Hold incoming webmentions for review instead of publishing automatically |
notify | boolean | false | Send email notifications for new webmentions (requires your endpoint to support this) |
[dev]: Development Settings
Configure the local development server.
| Field | Type | Default | Description |
|---|---|---|---|
base_url | string (optional) | none | Base URL for local development (e.g., http://localhost:8080) |
port | integer | 8080 | Port for the local development server |
[deploy]: Deployment Settings
Configure remote deployment via listsome deploy.
| Field | Type | Default | Description |
|---|---|---|---|
host | string (optional) | none | Remote host (e.g., your-server.local) |
user | string (optional) | none | SSH user for remote deployment |
path | string (optional) | none | Remote path where the site will be deployed |
port | string (optional) | none | Port for accessing the deployed site (used in output messages) |
[fediverse]: Fediverse Syndication
Configure automatic posting to Mastodon when you publish or update a project.
| Field | Type | Default | Description |
|---|---|---|---|
enabled | boolean | false | Enable auto-syndication |
mastodon_instance | string | https://mastodon.social | Your Mastodon instance URL |
mastodon_token | string | (empty) | Your Mastodon API token |
auto_syndicate | boolean | false | Automatically post when a project is published or updated |
default_hashtags | array | ["#DIY", "#makers"] | Hashtags to include in syndicated posts |
To get a Mastodon API token: settings → Development → New Application, then copy the access token.
Author Fallback
When creating a project, the author is determined in this order:
--authorflag onlistsome newauthorfield in the project’s frontmattersite.authorfromlistsome.tomlUSERorUSERNAMEenvironment variable"Anonymous"as final fallback
Command-line Tool Flags
These fields can also be set via command-line tool flags on listsome init:
| Flag | Config Field |
|---|---|
--name | site.name |
--author | site.author |
--url | site.url |
--about | site.about |