This guide walks you through everything you need — no coding experience required. By the end you will have a working website with your own content, published for free on GitHub Pages.

What you will need

• A free GitHub account
• Node.js installed on your computer (choose the “LTS” version)
• A code editor — Visual Studio Code is free and easy to use
• About 30 minutes

Step 1 — Get a copy of s:CMS

1. Go to the s:CMS repository on GitHub.
2. Click the green “Use this template” button, then “Create a new repository”.
3. Give your repository a name (e.g. my-site), keep it Public, and click “Create repository”.
4. On your computer, open a terminal (on Mac: Terminal app; on Windows: Command Prompt or PowerShell) and run:

1
git clone https://github.com/YOUR-USERNAME/my-site.git
2
cd my-site
3
npm install

Replace YOUR-USERNAME with your GitHub username and my-site with your repository name.

Once installation finishes, start the local preview server:

1
npm run dev

Open your browser at http://localhost:4321 — you should see the s:CMS default homepage.

Step 2 — Make the site yours

Open the file usr/user.config.mjs in your code editor. You will see two sections to fill in:

1
export const userConfig = {
2
  site: 'https://YOUR-USERNAME.github.io/my-site', // ← your future website URL
3
};
4

5
export const siteMetadata = {
6
  title: 'My Research Site',          // ← name shown in the browser tab and header
7
  description: 'A short description', // ← used by search engines
8
  author: 'Your Name',
9
};

Save the file. The preview in your browser updates automatically.

Step 3 — Add your content

All your content lives inside usr/content/. The folder is already organised into collections:

Creating a blog post

Create a new file, for example usr/content/blog/my-first-post.md, and paste this template:

1
---
2
title: 'My First Post'
3
description: 'A short description of this post'
4
date: 2026-01-01
5
author: 'Your Name'
6
tags: ['news']
7
---
8

9
Write your content here in plain text.
10

11
## A section heading
12

13
More text, **bold**, *italic*, [a link](https://example.com).

The block between the --- lines is called frontmatter — it holds the metadata for your post. Everything below it is your article text, written in plain Markdown.

Save the file and check http://localhost:4321/blog — your post appears immediately.

Adding images

Place image files next to your content file, inside the same folder:

1
usr/content/blog/
2
├── my-first-post.md
3
└── my-first-post/
4
    └── photo.jpg

Then reference them in your post with a standard Markdown image tag:

1
![Photo caption](./my-first-post/photo.jpg)

No extra copy steps needed — s:CMS handles the rest.

Step 4 — Create a new collection (optional)

If blog and docs do not fit your needs, you can create your own collection. The following example creates a projects collection.

4a. Create the folder usr/content/projects/ and add a Markdown file inside it, e.g. project-one.md:

1
---
2
title: 'Project One'
3
description: 'A short description'
4
date: 2026-01-01
5
---
6

7
Project details here.

4b. Open usr/content/config.ts and register the new collection by adding a few lines:

1
import { defineCollection, z } from 'astro:content';
2
import { glob } from 'astro/loaders';
3

4
const projectsCollection = defineCollection({
5
  loader: glob({ pattern: '**/*.{md,mdx}', base: './usr/content/projects' }),
6
  schema: z.object({
7
    title: z.string(),
8
    description: z.string(),
9
    date: z.coerce.date(),
10
  }),
11
});
12

13
export const collections = {
14
  blog: blogCollection,
15
  docs: docsCollection,
16
  data: dataCollection,
17
  projects: projectsCollection, // ← add this line
18
};

4c. Create the page usr/pages/projects/index.astro to list all projects. Use the existing usr/pages/blog/index.astro as a starting point — copy it, then replace every occurrence of 'blog' with 'projects' and adjust the title text.

Step 5 — Customise the navigation menu

Open usr/layouts/BaseLayout.astro. Near the top you will find a menuItems array — edit it to add or remove links:

1
const menuItems = [
2
  { href: '/',         label: 'Home',     isActive: currentPath === '/' },
3
  { href: '/blog',     label: 'Blog',     isActive: currentPath.startsWith('/blog') },
4
  { href: '/projects', label: 'Projects', isActive: currentPath.startsWith('/projects') },
5
];

Step 6 — Publish to GitHub Pages

6a. In your repository on GitHub, go to Settings → Pages. Under “Source”, select “GitHub Actions”.

6b. In your code editor, create the file .github/workflows/deploy.yml with this content:

1
name: Deploy to GitHub Pages
2

3
on:
4
  push:
5
    branches: [main]
6

7
jobs:
8
  deploy:
9
    runs-on: ubuntu-latest
10
    permissions:
11
      contents: read
12
      pages: write
13
      id-token: write
14
    environment:
15
      name: github-pages
16
      url: ${{ steps.deployment.outputs.page_url }}
17
    steps:
18
      - uses: actions/checkout@v4
19
      - uses: actions/setup-node@v4
20
        with:
21
          node-version: 22
22
      - run: npm install
23
      - run: npm run build
24
      - uses: actions/upload-pages-artifact@v3
25
        with:
26
          path: dist/
27
      - id: deployment
28
        uses: actions/deploy-pages@v4

6c. If your repository is not at the root of a domain (e.g. it will live at https://username.github.io/my-site rather than https://username.github.io), open usr/user.config.mjs and also set the base path:

1
export const userConfig = {
2
  site: 'https://YOUR-USERNAME.github.io/my-site',
3
  base: '/my-site',  // ← uncomment and fill in your repository name
4
};

6d. Commit and push everything to GitHub:

1
git add .
2
git commit -m "Initial site setup"
3
git push

GitHub Actions will build and deploy your site automatically. After about a minute, visit https://YOUR-USERNAME.github.io/my-site — your site is live.

From now on, every time you push a change to the main branch, the site rebuilds and publishes itself.

Quick reference