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 — Create your site

On your computer, open a terminal (on Mac: Terminal app; on Windows: Command Prompt or PowerShell) and run:

1
npx --package=@lad-sapienza/scms-core scms-create my-site

You’ll be asked a few questions (site title, description, author, site URL) — answer them, then it scaffolds a minimal site and installs its dependencies for you.

Once it finishes, start the local preview server:

1
cd my-site
2
npm run dev

Open your browser at http://localhost:4321 — you should see your new site’s homepage.

Step 2 — Make the site yours

Open the file src/user.config.mjs in your code editor. You will see two sections — scms-create already filled these in from your answers, but you can edit them any time:

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 first content collection

A freshly created site starts with no content collections at all — src/content.config.ts is empty. The fastest way to add one:

1
npm run add-collection

This asks for a name (e.g. blog) and a type (blog / docs / generic), then creates the schema in src/content.config.ts, a sample content file, and listing + detail page templates — everything you need to see it working immediately at npm run dev.

Adding a content file

Once a collection exists, add content to it the same way:

1
npm run add-content

Or create the file by hand, e.g. src/content/blog/my-first-post.md:

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
src/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 — Customise the navigation menu

Open src/layouts/BaseLayout.astro and find the <BSNavbar> tag. A freshly created site starts with an empty menu (menuItems={[]}) — replace it with your links:

1
<BSNavbar
2
  client:load
3
  menuItems={[
4
    { href: '/', label: 'Home' },
5
    { href: '/blog', label: 'Blog' },
6
  ]}
7
  currentPath={currentPath}
8
  ...
9
/>

Each entry needs a label and, usually, an href. The active link is worked out automatically from the current page — no isActive flag to set. Entries can also nest via children (up to 3 levels) for dropdown menus, e.g. { label: 'Docs', children: [{ href: '/docs/guides/getting-started', label: 'Getting Started' }] }.

Step 5 — Publish to GitHub Pages

5a. Create a new, empty repository on GitHub, then push your site to it:

1
git init
2
git add .
3
git commit -m "Initial site setup"
4
git branch -M main
5
git remote add origin https://github.com/YOUR-USERNAME/my-site.git
6
git push -u origin main

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

5c. scms-create already included a working deploy workflow at .github/workflows/deploy.yml — you don’t need to create anything. It builds with npm run build and publishes dist/ on every push to main. Open it if you want to customize the Node version or add build steps.

5d. 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 src/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
};

Commit and push this change too — 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