Momo comes with the parts most blogs need: post listings, archives, search, RSS, and light and dark themes. You mainly need to add your site details, write posts, and publish the generated files.
Momo is an open-source blog theme built with Astro. It supports Markdown, multiple languages, Pagefind search, and RSS. This guide follows Momo 26.8.15, which is based on Astro 7 and requires Node.js 22 or later. The project recommends Node.js 24 LTS.Momo theme page · Momo release notes
Install Git, Node.js 24 LTS, and pnpm. Check that the commands are available:
git --version
node --version
pnpm --versionIf pnpm is missing, install it with npm:
npm install --global pnpmInstall Astro and the theme dependencies in the project. Astro itself does not need to be installed globally.Astro installation guide
Clone Momo, install dependencies, and start the development server:
git clone https://github.com/Motues/Momo.git my-blog
cd my-blog
pnpm install
pnpm devOpen the local address printed in the terminal, usually http://localhost:4321. Check that the homepage loads before changing the configuration.
Create an empty repository on GitHub, then push your local repository. Keep the theme repository as upstream and use your own repository as origin:
git remote rename origin upstream
git remote add origin https://github.com/your-name/your-repository.git
git push -u origin HEADUse origin to publish your blog and upstream to check for theme updates. Leave the new GitHub repository empty so an automatically created README does not conflict with the local history.
In astro.config.mjs, set site and base for a GitHub Pages project repository:
export default defineConfig({
site: 'https://your-name.github.io',
base: '/your-repository',
// Keep the other theme configuration
})site is the domain; base is the repository path. If the repository is named your-name.github.io, the site is published at the domain root and usually does not need base. For a custom domain, set site to that domain and remove base. Internal links must also account for the base prefix.Astro: Deploy to GitHub Pages
In src/config.ts, find siteConfig and profileConfig, then replace the title, description, avatar, and other details with your own. Put the example avatar at public/avatar.png:
title: "My Blog",
subTitle: "Notes on technology, reading, and life",
favicon: "avatar.png",avatar: "/avatar.png",
name: "Your Name",
description: "A developer who enjoys building for the web",
indexPage: "https://your-name.github.io/your-repository",The configuration also covers the table of contents, post navigation, theme effects, comments, license, and friend links. Change only the values you need and keep the other fields from your version of the theme.Momo configuration guide
The homepage cover text lives in the language files under src/i18n/language/; edit cover.title and cover.subtitle. The languages available on the site and the default language are configured in astro.config.mjs.Momo configuration guide
Momo organizes posts by directory. Create a folder under src/content/blog/ and add one file per language:
src/content/blog/my-first-post/
├─ zh-cn.md
└─ en.mdEach post starts with YAML frontmatter:
---
title: "My first post"
pubDate: 2026-10-04
description: "My first post with Momo."
category: Notes
image: ""
draft: false
slugId: my-first-post
pinTop: 0
---
## Start here
Write your post here.title, pubDate, and a unique slugId are required. Posts with draft: true stay out of the production site. Use image for a cover, category to group posts, and pinTop to control pinned order. Momo builds the post route from its relative directory under src/content/blog/; slugId identifies the post and is also used by the comment system. Avoid renaming a published directory or reusing its slugId.Momo: Publish a post
Put translations in the same directory and use the same slugId. Name the English file en.md, and enable each language in astro.config.mjs. If a translation is missing, Momo falls back to the default language.
Build and preview the production output before publishing:
pnpm build
pnpm previewThe build creates the static files in dist/ and generates the Pagefind search index. Check the pages, images, and search in the preview.
First check whether .github/workflows/ already contains a Pages workflow. If it does not, follow the Astro deployment guide to add a GitHub Actions workflow that installs dependencies, runs the build, uploads dist/, and deploys it to Pages. Use the same Node.js version and package manager as the project. Commit the matching lock file: pnpm-lock.yaml for pnpm or package-lock.json for npm.
In the GitHub repository, open Settings → Pages and set Source to GitHub Actions. After a successful local build, commit and push your changes:
git status
git add .
git commit -m "Build my Momo blog"
git pushCheck the Actions tab to follow the build and deployment. A project repository is published at https://your-name.github.io/your-repository/. Astro’s Pages workflow detects the package manager from the lock file, so commit that file with the rest of the source.Astro: Deploy to GitHub Pages
If the workflow fails, open the failed Build step and find the first error. Then reproduce it locally with pnpm build. Check the Node.js version, lock file, post frontmatter, and site and base values.
GitHub Pages serves static files; comments need a separate backend. Momo provides Momo Backend. After deploying it, enable comments in src/config.ts and enter the backend URL:
comments: {
enable: true,
platform: "default",
backendUrl: "https://your-comment-backend.example.com"
}The backend must allow requests from your blog’s domain through CORS. localhost works only on the computer running the backend; visitors need a publicly reachable URL. Momo also supports Twikoo, so check the configuration and backend documentation for your version.Momo: Deploy the comment system
Version and feature details are based on Momo 26.8.15 and were checked on 2026-10-04. Astro and Momo evolve; when upgrading, follow the configuration files and release notes for the version you use.
Loading comments...