Getting Started with Mare Blog: Configuration and Usage Guide

1. Deploying to Cloudflare Pages

You can deploy your own copy of Mare Blog using Cloudflare Pages’ Git integration:

Deploy to Cloudflare Pages

Sign in to Cloudflare, connect GitHub, and select your fork or copy of the repository. Configure the project with:

Setting Value
Framework preset Astro
Build command pnpm build
Build output directory dist

The build command runs Astro and creates the Pagefind search index. Once the first deployment succeeds, pushes to the connected branch trigger new builds. After deployment, update url in site.config.ts to your site’s public URL.

2. Configuring Your Site

All global site metadata and third-party integrations are managed in site.config.ts.

This project ships with a working default configuration that you can customize to fit your site:

export default defineConfig({
  lang: "en",
  title: "Mare Blog",
  description: "A minimal, lightning-fast personal blog built with Astro.",
  author: "Niceeepoiu",
  authorUrl: "https://www.github.com/Niceeepoiu",
  authorBio: "A passionate developer.",
  authorLocation: "Zhejiang, China",
  avatar: "https://www.github.com/Niceeepoiu.png",
  authorLinks: [
    {
      name: "GitHub",
      href: "https://www.github.com/Niceeepoiu",
      icon: "lucide:github",
    },
  ],
  url: "https://mare-blog.pages.dev",
  postsPerPage: 6,
  nav: [
    { name: "Home", href: "/", icon: "lucide:home" },
    { name: "Blog", href: "/blog", icon: "lucide:book-open" },
    { name: "Journal", href: "/journal", icon: "lucide:calendar-days" },
    { name: "Tags", href: "/blog/tags", icon: "lucide:tags" },
    { name: "About", href: "/about", icon: "lucide:user" },
  ],
  giscus: {
    enabled: true,
    repo: "Niceeepoiu/mare-blog",
    repoId: "R_kgDOUH3Ucg",
    category: "Announcements",
    categoryId: "DIC_kwDOUH3Ucs4DEfws",
    theme: "light",
    darkTheme: "dark",
    lang: "en",
  },
});

The project defaults to Giscus enabled, but comments only render if the repository, repository ID, category, and category ID are all valid.

Configuration Options Breakdown

Main Site Metadata

  • lang: The site’s language code.
  • title: The global title of your blog used in SEO meta tags and the header.
  • description: Default meta description used for social sharing and search engines.
  • author: The name displayed in post footers and other author metadata.
  • authorUrl: External link to your GitHub, personal website, or portfolio.
  • authorBio: Short introduction used in author-related UI blocks.
  • authorLocation: Optional location text displayed with the author profile.
  • avatar: URL for the author avatar image.
  • authorLinks: Optional list of profile links such as GitHub, X, or LinkedIn.
  • url: The public base URL of the site.
  • postsPerPage: Number of posts displayed on each blog archive page.
  • nav: Array of header links. Each item requires name and href; icon is optional and uses identifiers like lucide:home.

Giscus Comment System Settings

  • enabled: Toggle true or false to show or hide comments globally.
  • repo: GitHub repository in owner/repo format.
  • repoId: Repository GraphQL node ID generated by giscus.
  • category: The discussion category name to use for comments.
  • categoryId: Category GraphQL node ID generated by giscus.
  • theme: Theme name used in light mode.
  • darkTheme: Theme name used in dark mode.
  • lang: Language code used by the comment widget UI.

Step-by-Step Guide: How to Obtain Giscus Credentials

Follow these steps to generate your required repoId and categoryId:

  1. Prepare Your GitHub Repository:

    • Ensure your repository is public (Giscus does not work with private repositories).
    • Enable the Discussions feature in the repository settings.

  2. Install the Giscus App:

  3. Generate Credentials via the Giscus Website:

    • Go to giscus.app.
    • Enter your repository path in the Repository field.
    • Choose a suitable discussion category.
    • Copy the generated data-repo-id and data-category-id values.
    • Paste them into /site.config.ts and keep enabled: true.

To customize the site, update the fields in site.config.ts. You can change the content and structure independently.

3. Modifying the About Page

The About page is an MDX file at src/content/page/about.mdx.

To update your personal bio:

  1. Open the About MDX file.
  2. Update the Frontmatter metadata at the top if needed.
  3. Edit the content below the Frontmatter to update your personal intro, project showcase, or social media links. Since MDX is enabled, you can also embed Astro or JSX components seamlessly.
---
title: "About"
description: "Learn more about me and this blog."
---

Write your Markdown or MDX content here.

4. Writing & Publishing Posts

Blog articles live inside the content directory: src/content/blog/.

To publish a new article:

  1. Create a new .md or .mdx file in src/content/blog/ (e.g., my-first-post.md).
  2. Add the required Frontmatter metadata at the top of the file. Set featured to true if the post should appear in the homepage’s featured section; it defaults to false when omitted.
---
title: "Blog Title"
description: "A short description of the post..."
pubDate: 2026-08-30T09:00:00
featured: true
tags: [astro, writing]
---

Write your Markdown or MDX content here.

Every new post appears in the blog list. Only posts with featured: true appear in the homepage’s featured section. If no posts are featured, the section shows an empty-state message.

Use the optional tags field to group related posts. Tags appear on article cards and article pages, link to their tag archive, and are listed at /blog/tags. Posts without tags remain valid and are omitted from the tag index.

tags:
  - astro
  - writing

5. Keeping a Journal

Short notes and moments can be published on the Journal timeline without appearing in the blog archive. Create a .md or .mdx file in src/content/journal/ with a title and date/time:

---
title: "A small note"
pubDate: 2026-09-26T14:30:00
---

Write a short note here. Markdown content appears directly on the timeline.

Entries are sorted newest first. The date and time appear beside each entry on the left; its title and content appear on the right. Use the same YYYY-MM-DDTHH:mm:ss format for blog posts and journal entries.

6. Commands

All commands are run from the root of the project, from a terminal:

Command Action
pnpm install Installs dependencies
pnpm dev Starts local dev server at localhost:4321
pnpm build Builds your production site to ./dist/
pnpm preview Previews your build locally, before deploying
pnpm format Formats code across the project using Prettier
pnpm astro ... Runs Astro CLI commands
pnpm astro -- --help Gets help using the Astro CLI
astroblogging