Getting Started with Mare Blog: Configuration and Usage Guide

1. 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.

When enabled is on but the repo credentials are incomplete, the UI shows a clear disabled state and keeps navigation working smoothly without breaking the page.

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 and keep the rest of the project unchanged unless you also want to revise the site structure or content.

2. Modifying the About Page

The About page content is managed via MDX and located 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.

3. 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

4. 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.

5. Commands

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