This theme was developed during my free time, and the documentation may not be comprehensive enough, but I will try my best to explain it.

Prerequisite

Before starting, ensure you have the following tools installed in your development environment:

• Node.js - Required for running the development environment.
• pnpm - Our preferred package manager for dependency management.
• Git - For version control and project management.
• VS Code - Recommended code editor with excellent development experience.

Startup project

There are two ways to do this:

• Fork the repository
• Use this template - In the future, content-free branches will be launched, which do not require deleting and replacing content.

After you have your own repository, you can clone it to your local machine.

Update Theme

When the theme releases a new version, you can pull the latest changes without losing your content by following these steps:

1. Add upstream remote (only needed once)

git remote add upstream https://github.com/Dnzzk2/Litos.git

2. Fetch and merge the latest theme

git fetch upstream
git merge upstream/main --no-edit

3. Resolve conflicts (if any)

Conflicts typically only occur in files you have modified, such as src/config.ts. In that case, just keep your own configuration and accept the rest of the theme updates.

End

The following documents will be divided into pages, such as readme, posts…

The following files are compatible with this document:

• src/pages/index.astro - readme page.
• src/config.ts - readme page config.
• src/components/base - most of the components come from here.

Site Config

Configure basic site information:

export const SITE: Site = {
  title: 'Litos',
  description: 'Litos is a blog theme built with Astro.js and Dnzzk2.',
  website: 'https://litos.vercel.app/',
  lang: 'en',
  base: '/',
  author: 'Dnzzk2',
  ogImage: '/og-image.jpg',
}

Header Links

Top jump link component configuration:

export const HEADER_LINKS: Link[] = [
  {
    name: 'Posts',
    url: '/posts',
  },
]

Footer Links

Footer link component configuration:

export const FOOTER_LINKS: Link[] = [
  {
    name: 'Readme',
    url: '/',
  },
]

Social Links

In the readme page, you can see a string of icons below the theme introduction, which can be configured below. Icons are from Iconify.

export const SOCIAL_LINKS: SocialLink[] = [
  {
    name: 'github',
    url: 'https://github.com/yourname',
    icon: 'icon-[ri--github-fill]',
    count: 11,
  },
  {
    name: 'twitter',
    url: 'https://x.com/yourname',
    icon: 'icon-[ri--twitter-x-fill]',
  },
]

Spotlight

export const GITHUB_CONFIG: GithubConfig = {
  ENABLED: true,
  GITHUB_USERNAME: 'Dnzzk2',
  TOOLTIP_ENABLED: true,
}

Skills

On the readme page, you can see a skill display area where you can showcase your skills by configuring the following code:

export const SKILLSSHOWCASE_CONFIG: SkillsShowcaseConfig = {
  SKILLS_ENABLED: true,
  SKILLS_DATA: [
    {
      direction: 'left',
      skills: [
        {
          name: 'JavaScript',
          icon: 'icon-[mdi--language-javascript]',
        },
        {
          name: 'CSS',
          icon: 'icon-[mdi--language-css3]',
        },
        {
          name: 'HTML',
          icon: 'icon-[mdi--language-html5]',
        },
        {
          name: 'TypeScript',
          icon: 'icon-[mdi--language-typescript]',
        },
      ],
    },
  ],
}

Posts

Here, we mainly display pinned posts. If there are no pinned posts, we will display the latest number of size posts based on POSTS_CONFIG.

The following files are compatible with this document:

• src/pages/posts/[...id].astro - post specific content display page.
• src/pages/posts/[...page].astro - post list page.
• src/content/posts - posts collection
• src/content.config.ts - posts dataset and frontmatter configuration.
• ec.config.mjs - expressiveCode config.
• plugins/index.ts - remark and rehype plugins.
• src/config.ts - posts page config.
• src/components/posts - most of the components come from here.

Posts Page Config

The posts page config is configured in the following code:

export const POSTS_CONFIG: PostConfig = {
  title: 'Posts',
  description: 'Posts by Dnzzk2',
  introduce: 'Here, I will share the usage instructions for this theme to help you quickly use it.',
  author: 'Dnzzk2',
  homePageConfig: {
    size: 3,
    type: 'compact',
  },
  postPageConfig: {
    size: 10,
    type: 'minimal',
  },
  tagsPageConfig: {
    size: 10,
    type: 'time-line',
  },
  ogImageUseCover: false,
  postType: 'metaOnly',
  imageDarkenInDark: true,
  readMoreText: 'Read more',
  prevPageText: 'Previous',
  nextPageText: 'Next',
  tocText: 'On this page',
  backToPostsText: 'Back to Posts',
  nextPostText: 'Next Post',
  prevPostText: 'Previous Post',
  recommendText: 'REC',
}

There are a few configuration attributes, please refer to the table below for details.

Type & PostType

In the above document, we mentioned configurable types for configuring the display style of list data on the readme page, posts page, and tags page, as well as configurable postTypes for displaying metadata at the top of the posts content page.

Here is the specific style display of type:

Here is the specific style display of postType:

Frontmatter

After discussing the external list and overall design of the post, let’s take a look at the content of the post together. These contents are all in the src/content/posts folder.

Below is the frontmatter of the post content:

---
title: 'Litos: Posts Page Config'
description: ''
pubDate: 2025-08-13
author: 'Dnzzk2'
recommend: true
tags: ['Litos', 'Documentation']
---

You can configure the frontmatter of the post content in the following code:

const posts = defineCollection({
  loader: glob({
    pattern: '**/*.{md,mdx}',
    base: './src/content/posts',
  }),
  schema: ({ image }) =>
    z
      .object({
        title: z.string(),
        description: z.string(),
        pubDate: z.date(),
        tags: z.array(z.string()).optional(),
        updatedDate: z.date().optional(),
        author: z.string().default(POSTS_CONFIG.author),
        cover: image().optional(),
        ogImage: image().optional(),
        recommend: z.boolean().default(false),
        postType: z.custom<PostType>().optional(),
        coverLayout: z.custom<CoverLayout>().optional(),
        pinned: z.boolean().default(false),
        draft: z.boolean().default(false),
      })
      .transform((data) => ({
        ...data,
        ogImage: data.ogImage ? data.ogImage : POSTS_CONFIG.ogImageUseCover && data.cover ? data.cover : undefined,
      })),
})

Syntax and Code Style

This guide will show you how to format text using Markdown through a 3-day city trip itinerary. Learn Markdown while planning your journey!

Heading Levels

For travel notes, multiple heading levels help organize days, time blocks, and tips:

# 3-Day City Trip Itinerary

## Day 1: Arrival & Old Town

### Morning Plan

#### Coffee Stops

##### Metro Tips

###### Notes

Text Formatting

When writing travel notes, highlight important info:

Must-see spots should be bold Flexible time uses italics Critical cautions can use both Optional detours use strikethrough

**Must-see spots** should be bold
_Flexible time_ uses italics
**_Critical cautions_** can use both
~~Optional detours~~ use strikethrough

Packing List (Unordered List)

• Passport, visa
• Camera, extra battery
  • Bring a fast charger
  • Spare SD card
• Refillable water bottle
• Public transport card

- Passport, visa
- Camera, extra battery
  - Bring a fast charger
  - Spare SD card
- Refillable water bottle
- Public transport card

Day 1 Schedule (Ordered List)

1. Airport → hotel check-in
2. Old Town walking tour
3. Evening river cruise
   1. Arrive 15 min early
   2. Queue at Gate B
   3. Window seats recommended

1. Airport → hotel check-in
2. Old Town walking tour
3. Evening river cruise
   1. Arrive 15 min early
   2. Queue at Gate B
   3. Window seats recommended

Blockquotes

Traveler tip: Buy a 24‑hour metro pass if you plan 3+ rides in a day.

Save the hotel address in offline maps for quick access.

> Traveler tip: Buy a 24‑hour metro pass if you plan 3+ rides in a day.
>
> Save the hotel address in offline maps for quick access.

Code Blocks

Use simple code to estimate budget:

type Budget = { flight: number; hotel: number; meals: number; transport: number }
export const total = (b: Budget) => b.flight + b.hotel + b.meals + b.transport

console.log(total({ flight: 1200, hotel: 450, meals: 180, transport: 60 })) // 1890

Tables

Sample schedule:

Links and Images

More tips: Official Tourism Board

Trip photo:

Horizontal Rule

Inline Code

Metro line A runs every 5-7 minutes during peak hours.

Math Formulas

Daily budget estimation: budget=hotel+meals+transportbudget = hotel + meals + transportbudget=hotel+meals+transport

Total trip:

Task Lists

Pre-trip checklist:

• Book flights
• Reserve hotel
• Buy metro pass
• Download offline maps

Footnotes

This itinerary draws on local travel guides(click to the footnote) ¹.

Expressive-code config

In Markdown documents, we use code blocks to display code snippets and other content. This document explains how to customize the code block configuration.

The code blocks in this theme are configured using Expressive Code with all configuration options defined in the ec.config.mjs file. Below is the main configuration options:

import { defineEcConfig } from 'astro-expressive-code'
import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections'
import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers'

export default defineEcConfig({
  defaultLocale: 'zh-CN',
  defaultProps: {
    wrap: false,
    collapseStyle: 'collapsible-auto',
    showLineNumbers: false,
    preserveIndent: true,
  },
  minSyntaxHighlightingColorContrast: 0,

  styleOverrides: {
    uiFontFamily: 'GeistMono, Input Mono, Fira Code, ShangguSansSCVF, monospace',
    uiFontSize: '1em',
    codeFontFamily: 'GeistMono, Input Mono, Fira Code, ShangguSansSCVF, monospace',
    codeFontSize: '14px',
    codeLineHeight: '1.4',
    borderRadius: '0',
    codePaddingBlock: '0.8571429em',
    codePaddingInline: '1.1428571em',
    borderColor: ({ theme }) => (theme.type === 'dark' ? '#24273a' : '#e6e9ef'),

    frames: {
      frameBoxShadowCssValue: false,
      inlineButtonBackgroundActiveOpacity: '0.2',
      inlineButtonBackgroundHoverOrFocusOpacity: '0.1',
    },
    textMarkers: {
      backgroundOpacity: '0.2',
      borderOpacity: '0.4',
    },
  },

  plugins: [
    pluginCollapsibleSections({
      defaultCollapsed: false,
    }),
    pluginLineNumbers(),
  ],

  themes: ['catppuccin-macchiato', 'catppuccin-latte'],
  themeCssSelector: (theme) => (theme.name === 'catppuccin-macchiato' ? '.dark' : ':root:not(.dark)'),
  useDarkModeMediaQuery: false,
  useStyleReset: false,
})

You can go to the website to view the configuration options of expressive-code.

Comment System (Gitalk)

The theme has a built-in Gitalk comment system that uses GitHub Issues as the comment backend. Each post automatically gets its own issue for comments.

Prerequisites

You need to create a GitHub OAuth App first:

1. Go to GitHub Developer Settings → OAuth Apps → New OAuth App.
2. Fill in the form:
   • Application name: Any name (e.g. My Blog Comments)
   • Homepage URL: Your site URL (e.g. https://yourdomain.com)
   • Authorization callback URL: Same as your site URL
3. After creation, copy the Client ID and generate a Client Secret.
4. Create a public repository on GitHub to store comment issues (e.g. blog-comments).

Configuration

Configure the comment system in src/config.ts:

export const COMMENT_CONFIG: CommentConfig = {
  enabled: true,
  system: 'gitalk',
  gitalk: {
    clientID: import.meta.env.PUBLIC_GITHUB_CLIENT_ID,
    clientSecret: import.meta.env.PUBLIC_GITHUB_CLIENT_SECRET,
    repo: 'blog-comments',
    owner: 'YourGitHubUsername',
    admin: ['YourGitHubUsername'],
    language: 'en-US',
    perPage: 5,
    pagerDirection: 'last',
    createIssueManually: false,
    distractionFreeMode: false,
    enableHotKey: true,
  },
}

Then set the environment variables. Create a .env file in the project root (refer to .env.example):

PUBLIC_GITHUB_CLIENT_ID=your-github-client-id
PUBLIC_GITHUB_CLIENT_SECRET=your-github-client-secret

Config Properties

This guide has made slight changes based on the markdown-mdx-extended-features.

Callouts

Supported by the rehype-callouts , you can configure the plugin in plugins/index.ts.

If you change the theme configuration (default: 'vitepress'), you will also need to update the imported CSS file in src/styles/pro.css (@import 'rehype-callouts/theme/yourconfig').

<!-- Callout type names are case-insensitive: 'Note', 'NOTE', and 'note' are equivalent. -->

<!-- vitepress -->

<!-- This is a _non-collapsible_ callout -->

> [!note]
> Note content.

> [!tip]
> Tip content.

> [!important]
> Important content.

> [!warning]
> Warning content.

> [!caution]
> Caution content.

> [!caution]- This is a **collapsible** callout
> Caution content.

> [!note]+ This is a **collapsible** callout
> Note content.

Fully-featured Code Blocks

Supported by astro-expressive-code with @expressive-code/plugin-collapsible-sections and @expressive-code/plugin-line-numbers plugins to add styling and extra functionality for code blocks.

To customize code block themes or functionality, modify the ec.config.mjs file at the project root after reviewing the Configuring Expressive Code, such as change themes, enable word wrap, or toggle line numbers.

Here’s a quick preview of what’s possible. Check the detailed guide for more info.

Syntax highlighting

console.log('This code is syntax highlighted!')

ANSI colors:
- Regular: Red Green Yellow Blue Magenta Cyan
- Bold:    Red Green Yellow Blue Magenta Cyan
- Dimmed:  Red Green Yellow Blue Magenta Cyan

256 colors (showing colors 160-177):
160 161 162 163 164 165
166 167 168 169 170 171
172 173 174 175 176 177

Full RGB colors:
ForestGreen - RGB(34, 139, 34)

Text formatting: Bold Dimmed Italic Underline

Code editor frames

// Use `title="my-test-file.js"`
console.log('Title attribute example')

// src/content/index.ts
// Use `// src/content/index.ts`
console.log('File name comment example')

Terminal frames

echo "This terminal frame has no title"

Write-Output "This one has a title!"

Marking full lines & line ranges

// Line 1 - targeted by line number
// Line 2
// Line 3
// Line 4 - targeted by line number
// Line 5
// Line 6
// Line 7 - targeted by range "7-8"
// Line 8 - targeted by range "7-8"

Selecting line marker types (mark, ins, del)

function demo() {
  console.log('this line is marked as deleted')
  // This line and the next one are marked as inserted
  console.log('this is the second inserted line')

  return 'this line uses the neutral default marker type'
}

Adding labels to line markers

// labeled-line-markers.jsx
<button role="button" {...props} value={value} className={buttonClassName} disabled={disabled} active={active}>
  {children && !active && (typeof children === 'string' ? <span>{children}</span> : children)}
</button>

Adding long labels on their own lines

// labeled-line-markers.jsx
<button role="button" {...props} value={value} className={buttonClassName} disabled={disabled} active={active}>
  {children && !active && (typeof children === 'string' ? <span>{children}</span> : children)}
</button>

Using diff-like syntax

+this line will be marked as inserted
-this line will be marked as deleted
this is a regular line

  function thisIsJavaScript() {
    // This entire block gets highlighted as JavaScript,
    // and we can still add diff markers to it!
-   console.log('Old code to be removed')
+   console.log('New and shiny code!')
  }

Marking individual text inside lines

// Plaintext search strings
function demo() {
  // Mark any given text inside lines
  return 'Multiple matches of the given text are supported'
}

Marking individual text inside lines

// Regular expressions
console.log('The words yes and yep will be marked.')

# Regular expressions
echo "Test" > /home/test.txt

// Regular expressions
If you only want to mark certain parts matched by your regular expression, you can use capture groups.

For example, the expression `/ye(s|p)/` will match yes and yep, but only mark the character s or p:

// Regular expressions
To prevent this special treatment of capture groups, you can convert them to non-capturing groups by adding ?: after the opening parenthesis. For example:

This block uses `/ye(?:s|p)/`, which causes the full
matching words "yes" and "yep" to be marked.

// Selecting inline marker types (mark, ins, del)
function demo() {
  console.log('These are inserted and deleted marker types')
  // The return statement uses the default marker type
  return true
}

Configuring word wrap per block

// Example with wrap
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

// Example with wrap=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

Configuring indentation of wrapped lines

// Example with preserveIndent (enabled by default)
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

// Example with preserveIndent=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

Collapsible sections

// All this boilerplate setup code will be collapsed
import { someBoilerplateEngine } from '@example/some-boilerplate'
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'

const engine = someBoilerplateEngine(evenMoreBoilerplate())

// This part of the code will be visible by default
engine.doSomething(1, 2, 3, calcFn)

function calcFn() {
  // You can have multiple collapsed sections
  const a = 1
  const b = 2
  const c = a + b

  // This will remain visible
  console.log(`Calculation result: ${a} + ${b} = ${c}`)
  return c
}

// All this code until the end of the block will be collapsed again
engine.closeConnection()
engine.freeMemory()
engine.shutdown({ reason: 'End of example boilerplate code' })

Displaying line numbers per block

// This code block will show line numbers
console.log('Greetings from line 2!')
console.log('I am on line 3')

// Line numbers are disabled for this block
console.log('Hello?')
console.log('Sorry, do you know what line I am on?')

// Changing the starting line number
console.log('Greetings from line 5!')
console.log('I am on line 6')

Image Caption & Link

Use the :::image directive from remark-directive-sugar to wrap images in a container for captions, clickable links, and more. Customize via the image option in plugins/index.ts (remarkDirectiveSugar) and style under /* :::image */ in src/styles/pro.css.

image-figure

:::image-figure[caption]{<figcaption> attrs}: The square brackets define the <figcaption> text (defaults to the alt text from ![]() if omitted), while the curly braces are used for inline styles or supported attributes to the generated <figcaption> element.

![alt](image path)(<img> attrs): Standard Markdown image with optional attributes in parentheses, enabled by remark-imgattr, for customizing the generated <img> element.

:::image-figure[caption]{<figcaption> attrs}: The square brackets define the <figcaption> text (defaults to the alt text from ![]() if omitted), while the curly braces are used for inline styles or supported attributes to the generated <figcaption> element.

![alt](image path)(<img> attrs): Standard Markdown image with optional attributes in parentheses, enabled by remark-imgattr, for customizing the generated <img> element.

:::image-figure[This Is a **Figcaption** with _`<figure>` Attrs_]{style="text-align:center;color:orange"}
![](assets/cover.png)
:::

:::image-figure[This is a **figcaption** with _`<img>` attrs_.]
![](assets/cover.png)(style: width:600px;)
:::

<!-- 💡 Use `(class:no-zoom)` to disable zoom -->

:::image-figure[This is a **figcaption** with `class:no-zoom`.]
![](assets/cover.png)(class:no-zoom)
:::

<!-- 💡 If no `[caption]`, use `[alt]` as figcaption. -->

:::image-figure
![If `[caption]` not set, the alt text from `![]()` will be used as the figcaption.](assets/cover.png)
:::

<!-- 💡 Images for light (img-light) and dark (img-dark) modes -->
<!-- ⚠️ At least one line must separate two image syntaxes (![]()), or won't work. -->

:::image-figure[This example shows different images for light (add `class:img-light`) and dark (add `class:img-dark`) modes.]
![](assets/image-16-9-light.png)(class:img-light)

![](assets/image-16-9-light.png)(class:img-dark)
:::

<!-- ❌ If no text is available for the figcaption, it won't work.  -->

:::image-figure
![](assets/cover.png)
:::

image-a

The custom directive wraps an image inside a link, making it clickable.

:::image-a{<a> attrs}: Define the link (href), styles, or classes in the curly braces for <a> element.

![alt](image path)(<img> attrs): Same as above.

:::image-a{href="https://github.com/Dnzzk2/Litos"}
![OG image](assets/cover.png)
:::

:::image-a{href="https://github.com/Dnzzk2/Litos" style="display:block" .custom-class}
![OG image](assets/cover.png)(style: margin-bottom: -1rem; transform:scaleX(1.1) scaleY(1.1);, loading: eager)
:::

::::image-a{href="https://github.com/Dnzzk2/Litos"}
:::image-figure[This example shows `:::image-a` wraps around `:::image-figure` (both are interchangeable).]
![OG image](assets/cover.png)
:::
::::

<!-- ❌ No external links provided, it won't work.-->

:::image-a
![OG image](assets/cover.png)
:::

image-figure-polaroid

Polaroid style images with a border and shadow.

In order to ensure the style size on the phone, I have set a minimum width of 300px, and you can modify and expand the style in src/styles/picture.css.

:::::image-div-polaroid
:::image-figure-polaroid[This is a **figcaption** with _`<img>` attrs_.]
![OG image](assets/cover.png)
:::
:::::

:::::image-div-polaroid
:::image-figure-polaroid
![OG image](assets/cover.png)

cover.png
:::
:::::

:::::image-div-polaroid
:::image-figure-polaroid
![OG image](assets/cover.png)
:::
:::::

<!-- change style -->

:::::image-div-polaroid
:::image-figure-polaroid{style="width:500px;"}
![OG image](assets/cover.png)
:::
:::::

This is a figcaption with <img> attrs.

cover.png

GitHub Card

Congratulations from oopsunix

::github{repo="Dnzzk2/Litos"}

Video Embedding

Use the ::video directive from remark-directive-sugar for consistent video embedding across different platforms. Customize via the video option in plugins/index.ts and style under /* ::video */ in src/styles/pro.css.

Say example.md contains:

<!-- Embed a YouTube video -->

::video-youtube{#gxBkghlglTg}

<!-- Embed a Bilibili video with a custom `title` attr -->

::video-bilibili[custom title]{id=BV1MC4y1c7Kv}

<!-- Embed a Vimeo video with class `no-scale` to disable scaling -->

::video-vimeo{id=912831806 class='no-scale'}

<!-- ::video-vimeo{id=912831806 .no-scale} -->

<!-- Embed a custom video URL (must use `id`, not `#`) -->

::video{id=https://www.youtube-nocookie.com/embed/gxBkghlglTg}

Then example.mdx renders as:

Styled Link（:link）

Use the :link directive from remark-directive-sugar to add links with avatars or favicons for GitHub, npm, or custom URLs. Customize via the link option in plugins/index.ts and style under /* :link */ in src/styles/pro.css.

Link to a GitHub user or organization (prepend id with @)

Example 1: :link[Dnzzk2]{#@Dnzzk2} links to the GitHub profile of the project maintainer, Dnzzk2.

Example 2: Vite links to the GitHub profile of the Vite organization.

Example 3: :link{#@Dnzzk2 tab=repositories} links directly to the repositories tab of the GitHub user, like Dnzzk2. For GitHub users, valid tab options: 'repositories','projects', 'packages', 'stars', 'sponsoring', 'sponsors'.

Example 4: :link{#@vitejs tab=org-people} links directly to the people section of a GitHub organization, like vitejs. For GitHub organizations, valid tab options: 'org-repositories', 'org-projects', 'org-packages', 'org-sponsoring', and 'org-people'.

Link to a GitHub repository

Example 5: :link[Astro]{#withastro/astro} or Astro creates a link to Astro repo.

Link to an npm package

Example 6: :link{#remark-directive-sugar} links to the npm homepage of the remark-directive-sugar.

Example 7: :link{id=remark-directive-sugar tab=dependencies} links to the dependencies section of the remark-directive-sugar on npm. For npm package, valid tab options: 'readme', 'code', 'dependencies', 'dependents', and 'versions'.

Link to a custom URL (must use id, not #)

Example 8: :link{id=https://developer.mozilla.org/en-US/docs/Web/JavaScript} creates an external link to the developer.mozilla.org/en-US/docs/Web....

Example 9: Google creates an external link to the Google.

Customization

Example 10: Vite creates a Vite to https://vite.dev/ instead of https://github.com/vitejs by using the url.

Example 11: Vite creates a Vite that displays a custom logo by using the img.

Example 12: :link{id=Dnzzk2/Litos class=github} creates a Dnzzk2/Litos with class=github (or .github) to override the default style of a GitHub repository.

Example 13: Litos Themes fully customizes a link. Litos Themes

Badges

Use the :badge directive from remark-directive-sugar to display small pieces of information, such as status or category.

The theme provides the following one predefined badges. You can customize them via the badge option in plugins/index.ts and style them under /* :badge */ in src/styles/pro.css.

• badge-n: NEW

Additionally, you can direct use :badge[text]{attrs} for easy visual customization of badges. For example: :badge[ISSUE]{style="background-color: #bef264"} will display as ISSUE. If no color is specified, the default appearance will look like This.

Details Dropdown

:::details
::summary[Details Dropdown]

- List item 1
- List item 2
- List item 3
- List item 4
  :::

• List item 1
• List item 2
• List item 3
• List item 4

Additionally, it also supports usage similar to the examples in remark-directive.

Due to the small size of the Project and tag page configurations, they are merged into one document.

The following files are compatible with this document:

• src/pages/projects/index.astro - project page.
• src/pages/tags/index.astro - tag statistics page.
• src/pages/tags/[tag]/[...page].astro - specific tag display post list page.
• src/config.ts - project and tag page config.
• src/components/base - most of the components come from here.

Project Page Config

Configure page texts:

export const PROJECTS_CONFIG: ProjectConfig = {
  title: 'Projects',
  description: 'The examples of my projects.',
  introduce: 'The examples of my projects.',
}

Project content

The content displayed on the project page comes from /src/content/projects.

Its writing style is similar to posts: one MDX file represents one project.

Project frontmatter

Example (src/content/projects/Litos/index.mdx):

---
name: 'Litos'
description: 'A Simple & Modern Blog Theme for Astro.'
githubUrl: 'https://github.com/Dnzzk2/Litos'
website: 'https://litos.vercel.app/'
type: 'image'
icon: '../../../../public/projects/litos.png'
imageClass: 'w-10 h-10'
star: 32
fork: 7
---

Tag Page Config

export const TAGS_CONFIG: TagsConfig = {
  title: 'Tags',
  description: 'All tags of Posts',
  introduce: 'All the tags for posts are here, you can click to filter them.',
}

This document describes the current implementation of the Photos page.

Current file structure

• src/pages/photos/index.astro
  • Reads page text from PHOTOS_CONFIG
  • Reads timeline data from PhotosList
• src/config.ts
  • Stores PHOTOS_CONFIG
• src/lib/photos.ts
  • Stores PhotosList
  • Auto-imports photo files
  • Converts one folder of images into Photo[] with getPhotos()
• src/types.ts
  • Defines PhotoData, Photo, and PolaroidVariant
• src/components/photos/PolaroidCard.tsx
  • Maps each variant to the actual card size

Page text

The page title and intro text come from src/config.ts.

export const PHOTOS_CONFIG: PhotosConfig = {
  title: 'Photos',
  description: 'Here I will record some photos taken in daily life.',
  introduce: 'Here I will record some photos taken in daily life.',
}

src/pages/photos/index.astro renders the page like this:

---
import { PHOTOS_CONFIG } from '~/config'
import { PhotosList } from '~/lib/photos'

const { title, description, introduce } = PHOTOS_CONFIG
---

<Layout {title} {description}>
  <PageTitle {title} {introduce} />
  <PhotoTimeline photoData={PhotosList} />
</Layout>

PhotosList

PhotosList is defined in src/lib/photos.ts. Each item is one timeline entry.

export const PhotosList: PhotoData[] = [
  {
    title: 'Ningbo - Botanical Garden',
    icon: { type: 'emoji', value: '🌼' },
    description: 'It was early spring, so I went to see the cherry blossoms.',
    date: '2026-03-07',
    travel: '',
    photos: getPhotos(
      '2026-03-07-botanicalGarden',
      'Early spring cherry blossoms at the botanical garden',
      ['3x4', '3x4', '3x4', '3x4', '3x4', '3x4']
    ),
  },
]

PhotoData fields

How getPhotos() works

Current implementation:

function getPhotos(dir: string, alt: string, variants: PolaroidVariant[]): Photo[] {
  return Object.entries(photoModules)
    .filter(([path]) => path.includes(`/${dir}/`))
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([, mod], index) => {
      const img = mod.default
      return {
        src: img,
        alt,
        width: img.width,
        height: img.height,
        variant: variants[index] || '4x3',
      }
    })
}

Parameter meaning

Important behavior

1. getPhotos() first filters all imported images by folder name.
2. It then sorts the matched file paths with localeCompare.
3. It creates the final Photo[] in that sorted order.
4. variants[index] is applied to the photo at the same index.
5. If one index is missing in variants, that photo falls back to '4x3'.

How the third parameter is matched

The third parameter is not random metadata. It is position-based.

For this code:

photos: getPhotos(
  '2026-03-07-botanicalGarden',
  'Early spring cherry blossoms at the botanical garden',
  ['3x4', '3x4', '3x4', '3x4', '3x4', '3x4']
)

Assume the folder src/assets/photos/2026-03-07-botanicalGarden/ contains these files after sorting:

01.webp
02.webp
03.webp
04.webp
05.webp
06.webp

Then the mapping is:

So if you want the first photo in the folder to use 3x4, the first item in the third array must be 3x4.

If you want mixed ratios, write them in the same order as the sorted files:

photos: getPhotos('2025-03-01-dongqianhu', 'Ningbo - Dongqian Lake', ['4x5', '1x1', '4x3'])

That means:

• first sorted image -> 4x5
• second sorted image -> 1x1
• third sorted image -> 4x3

If the folder contains more photos than the array length:

photos: getPhotos('example-folder', 'Example alt', ['3x4', '4x5'])

Then:

• first sorted image -> 3x4
• second sorted image -> 4x5
• third sorted image and later -> default 4x3

Supported variants

PolaroidVariant is currently:

export type PolaroidVariant = '1x1' | '4x5' | '4x3' | '3x4' | '9x16'

Current size mapping in src/components/photos/PolaroidCard.tsx:

const polaroidVariants: Record<PolaroidVariant, string> = {
  '1x1': 'w-20 h-20',
  '4x5': 'w-20 h-24',
  '4x3': 'w-20 h-16',
  '3x4': 'w-[4.5rem] h-24',
  '9x16': 'w-20 h-32',
}

How to add a new timeline entry

1. Create a folder under src/assets/photos/, for example 2026-04-01-spring-walk.
2. Put image files into that folder.
3. Make sure the file names are in the order you want after sorting.
4. Add one item to PhotosList in src/lib/photos.ts.
5. Pass the third argument to getPhotos() in the same order as the sorted files.

Example:

{
  title: 'Spring Walk',
  icon: { type: 'emoji', value: '🌿' },
  description: 'A short walk with a camera.',
  date: '2026-04-01',
  travel: '',
  photos: getPhotos(
    '2026-04-01-spring-walk',
    'Photos from a spring walk',
    ['3x4', '4x3', '4x5', '4x3']
  ),
}

Notes

• alt is applied to every photo returned from the same folder.
• The order is determined by sorted file path, not by import order in the editor.
• If you rename files, the sort order may change, and the variants array will then map to different photos.