Skip to content

2. Setup Guide ‐ Advanced

Jump to bottom
Kazimir edited this page Apr 22, 2025 · 9 revisions

You may also decide to use Saussure according to the beginner guide, where you clone the 11ty template and use the demo site to access your files.

However, you may wish to further customize Saussure by hosting your own version of the application, which can easily be done for free.

Deploying Your Own Copy of Saussure

I have a convenient "Deploy with Vercel" button in the README! Use that to deploy your own site, or fork and host your own with Cloudflare Workers or Netlify. Saussure runs on SvelteKit with the auto-adapter, and requires serverless functions in order to operate. Saussure does not connect to a database.

You may wish to change the line const url = github.createAuthorizationURL(state, ['public_repo']); in src/routes/login/github/+server.ts. By default, public_repo scope only allows for access to public repositories. You can change it to repo if you want to allow access to private ones.

Hosting Saussure requires you to create an OAuth App in your developer settings, either in GitHub or Forgejo/Gitea. Configure these environment variables as needed:

GH_CLIENT_ID=
GH_CLIENT_SECRET=
FORGEJO_CLIENT_ID=
FORGEJO_CLIENT_SECRET=

Creating Your Own Template/Using a Custom SSG

Saussure is theoretically agnostic when it comes to which SSG is supported. All you need to do is select "Custom" and configure your directories/layout locations accordingly.

Currently, these are the rendering engines supported for layout previews:

  • Markdown (.md)
  • Nunjucks (.njk)
  • Liquid (.liquid)
  • Handlebars (.hbs)

If you don't care about previews, you can use whatever you want.

Your SSG must be able to parse markdown files with HTML, as that is how Saussure stores its data.

Characters and literature are named by index, eg. 1.md, 2.md, etc. Images are stored according to filename + '.md' extension. No data is stored in nested folders -- organization is done purely through metadata, for maximum compatibility.

This is the format followed for character MD files:

---
name: [Name]
tags: 'comma,separated'
folder: [Folder Name]
[arbitrary fields]
---

[content]

The format for images:

---
character: [Filename for the character, such as 1.md or 2.md]
file: [Direct filename of the image with no path]
title: [Title]
tags: 'comma,separated'
[arbitrary fields]
---
[description]

And literature:

---
character: [Filename for the character, such as 1.md or 2.md]
title: [Title]
tags: 'comma,separated'
---
[content]

Restricting Access

You can restrict access to specific usernames on your copy of Saussure by configuring the ALLOWED_USERS environment variable.

S3 Support

If you wish to use S3 for image hosting, you must self-host your own copy of Saussure.

All accounts authorized to use your copy of Saussure will utilize your configured S3. This is because it's frankly not secure to store S3 credentials outside of environment variables, so it can not be done on a user-by-user basis. To account for this, you must also configure usernames that are allowed to log in.

Clone this wiki locally