2. Setup Guide ‐ Advanced

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.

There is a slightly more advanced version of the template available here (link pending), with included notes on how to utilize it.

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=

ALLOWED_USERS=

S3_ENDPOINT=
S3_BUCKET=
S3_ACCESS_KEY=
S3_SECRET_KEY=
PUBLIC_S3_URL=

Vercel will throw a fit if you don't have all of them, so just enter them in and keep as empty if needed.

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.

If your layouts use filters or other features not supported by the default template library, and you still want previews to work, you'll need to add handling for those circumstances. This can be done in src/lib/frontends/renderers.svelte.ts.

Characters and literature are named by index, eg. 1.md, 2.md, etc. Images are stored according to index + 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: [Comma separate list of the filename slugs for the characters]
file: [Direct filename of the image with no path]
title: [Title]
tags: 'comma,separated'
[arbitrary fields]
---
[description]

And literature:

---
characters: [Comma separate list of the filename slugs for the characters]
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. Anyone not registered will receive a 401 error message upon trying to authorize with your site.

S3 Support

If you wish to use S3 for image hosting, you must self-host your own copy of Saussure. I recommend using it over Git if you are storing a considerable amount of images, especially any NSFW. Backblaze has an amazing free plan!

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.

Configure the relevant environment variables, then go to the Settings and change Media Storage from "Git" to "S3".

Images are not automatically converted/shared between Git and S3. You'll have to choose one or the other!