Getting Started

1. Deploying to Cloudflare Pages

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

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

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.",
  authorDetails:
    "A student with basic full-stack development skills who enjoys playing Minecraft.",
  authorLocation: "Zhejiang, China",
  githubUsername: "Niceeepoiu",
  avatar: "/avatar.webp",
  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: "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.
• authorDetails: Detailed introduction displayed on the About page profile card. Separate paragraphs with a blank line.
• authorLocation: Optional location text displayed with the author profile.
• githubUsername: GitHub username used to display the contribution graph on the About page.
• 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:

   • Grant Giscus permission to access your repository by visiting github.com/apps/giscus.

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 profile card uses authorDetails in site.config.ts; its Markdown/MDX page content is rendered by src/pages/about.astro from src/content/page/about.mdx.

To update your personal bio:

1. Update authorDetails in site.config.ts to edit the profile card introduction.
2. Open the About MDX file to edit the page content.
3. Update the Frontmatter metadata at the top if needed.
4. Edit the content below the Frontmatter to update the page copy, project showcase, or 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-30
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. Managing Friend Links

The /friends page is linked from the main navigation. Its introduction and application instructions are editable in src/content/page/friends.mdx. Visitors can suggest a link in the Giscus comments using this format:

Site name:
Site URL:
Site introduction:
Avatar URL (optional):

Review submissions before adding them. Each published link is a YAML file in src/content/friend/; use a unique filename and provide a name, URL, and short description. The avatar is optional:

name: "Example Blog"
url: "https://example.com"
description: "Notes on design, code, and the web."
avatar: "https://example.com/avatar.png"
darkAvatar: "https://example.com/avatar-dark.png"

avatar and darkAvatar are optional. Omit avatar to use the site’s default icon. If darkAvatar is provided, it is shown in dark mode while avatar (or the default icon) is shown in light mode. Friend cards are generated from these files and sorted by name. The comment section follows the global giscus.enabled setting and the Giscus credentials in site.config.ts.

6. 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-26
---

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.

7. Commands

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