docs: update comments in theme guides and configuration files

This commit is contained in:
radishzzz 2025-05-08 02:32:12 +01:00
parent bf20fb4014
commit b72b59358b
9 changed files with 83 additions and 165 deletions

View file

@ -22,7 +22,7 @@ const linkPrefetch = themeConfig.preload.linkPrefetch
const imageHostURL = themeConfig.preload.imageHostURL
const imageConfig = imageHostURL
? {
// Configure domains and remotePatterns to optimize remote images in Markdown files using ![alt](src) syntax (adds width and height)
// Configure domains and remotePatterns to optimize remote images in Markdown files using ![alt](src) syntax
// Docs: https://docs.astro.build/en/guides/images/#authorizing-remote-images
image: {
domains: [imageHostURL],
@ -82,7 +82,7 @@ export default defineConfig({
],
],
shikiConfig: {
// available themes: https://shiki.style/themes
// Available themes: https://shiki.style/themes
themes: {
light: 'github-light',
dark: 'github-dark',

View file

@ -21,19 +21,19 @@ function formatDate(date: Date, format: 'YYYY-MM-DD' | 'MM-DD-YYYY' | 'DD-MM-YYY
}
switch (format) {
// ISO format: 2024-03-04
// ISO format: 2025-04-13
case 'YYYY-MM-DD':
return date.toISOString().split('T')[0]
// US date format: 03-04-2024
// US date format: 04-13-2025
case 'MM-DD-YYYY':
return date.toLocaleDateString('en-US', options).replace(/\//g, '-')
// European date format: 04-03-2024
// European date format: 13-04-2025
case 'DD-MM-YYYY':
return date.toLocaleDateString('en-GB', options).replace(/\//g, '-')
// US month text format: Mar 4 2024
// US month text format: Mar 13 2025
case 'MONTH DAY YYYY':
return date.toLocaleDateString('en-US', {
year: 'numeric',
@ -41,7 +41,7 @@ function formatDate(date: Date, format: 'YYYY-MM-DD' | 'MM-DD-YYYY' | 'DD-MM-YYY
day: 'numeric',
}).replace(',', '')
// British month text format: 4 Mar 2024
// British month text format: 13 Mar 2025
case 'DAY MONTH YYYY':
return date.toLocaleDateString('en-GB', {
year: 'numeric',

View file

@ -38,11 +38,8 @@ export const themeConfig: ThemeConfig = {
},
dark: {
// primary color
// used for title, hover, etc
// oklch color picker: https://oklch.com/
primary: 'oklch(92% 0.005 298)',
// secondary color
// used for post text
secondary: 'oklch(77% 0.005 298)',
// background color
background: 'oklch(22% 0.005 298)',
@ -55,7 +52,7 @@ export const themeConfig: ThemeConfig = {
// default language
locale: 'zh', // zh, zh-tw, ja, en, es, ru
// more languages
// not fill in the locale code above again
// not fill in the locale code above again, can be an empty array []
moreLocales: ['zh-tw', 'ja', 'en', 'es', 'ru'], // ['zh', 'zh-tw', 'ja', 'en', 'es', 'ru']
// font styles for post text
fontStyle: 'sans', // sans, serif
@ -84,7 +81,6 @@ export const themeConfig: ThemeConfig = {
// gif search
search: false, // true, false
// image uploader
// bug: unable to hide image uploader icon
imageUploader: false, // true, false
},
},

View file

@ -75,12 +75,13 @@ global: {
// language of the site root path '/'
locale: 'zh' // zh, zh-tw, ja, en, es, ru
// more languages
// Generate multi-language paths such as '/es/' '/ru/'
// do not include the default language again, can be an empty array []
// generate multi-language paths such as '/es/' '/ru/'
// not fill in the locale code above again, can be an empty array []
moreLocales: ['zh-tw', 'ja', 'en', 'es', 'ru'] // ['zh', 'zh-tw', 'ja', 'en', 'es', 'ru']
// font style
fontStyle: 'sans' // sans, serif
// date format for posts
// 2025-04-13, 04-13-2025, 13-04-2025, Mar 13 202513 Mar 2025
dateFormat: 'YYYY-MM-DD' // YYYY-MM-DD, MM-DD-YYYY, DD-MM-YYYY, MONTH DAY YYYY, DAY MONTH YYYY
// enable KaTeX for mathematical formulas rendering
katex: true // true, false
@ -205,11 +206,11 @@ Code block syntax highlighting themes.
// astro.config.ts
shikiConfig: {
// available themes: https://shiki.style/themes
// background color follows the blog theme by default, not the syntax highlighting theme
// Available themes: https://shiki.style/themes
// Background color follows the blog theme by default, not the syntax highlighting theme
themes: {
light: 'github-light' // light theme
dark: 'github-dark' // dark theme
light: 'github-light' // Light theme
dark: 'github-dark' // Dark theme
}
}
```
@ -241,23 +242,23 @@ Open Graph social image styles.
getImageOptions: (_path, page) => ({
logo: {
path: './public/icon/og-logo.png', // required local path and PNG format
size: [250], // logo width
path: './public/icon/og-logo.png', // Required local path and PNG format
size: [250], // Logo width
},
font: {
title: { // title
families: ['Noto Sans SC'], // font
weight: 'Bold', // weight
color: [34, 33, 36], // color
lineHeight: 1.5, // line height
title: { // Title
families: ['Noto Sans SC'], // Font
weight: 'Bold', // Weight
color: [34, 33, 36], // Color
lineHeight: 1.5, // Line height
},
},
fonts: [ // font paths (local or remote)
'https://raw.githubusercontent.com/notofonts/noto-cjk/main/Sans/SubsetOTF/SC/NotoSansSC-Bold.otf',
'https://raw.githubusercontent.com/notofonts/noto-cjk/main/Sans/SubsetOTF/SC/NotoSansSC-Regular.otf',
fonts: [ // Font paths (local or remote)
'https://cdn.jsdelivr.net/gh/notofonts/noto-cjk@main/Sans/SubsetOTF/SC/NotoSansSC-Bold.otf',
'https://cdn.jsdelivr.net/gh/notofonts/noto-cjk@main/Sans/SubsetOTF/SC/NotoSansSC-Regular.otf',
],
bgGradient: [[242, 241, 245]], // background color
// more configurations: https://github.com/delucis/astro-og-canvas/tree/latest/packages/astro-og-canvas
bgGradient: [[242, 241, 245]], // Background color
// More configurations: https://github.com/delucis/astro-og-canvas/tree/latest/packages/astro-og-canvas
})
```
@ -269,9 +270,9 @@ RSS feed page styles.
<!-- public/rss/rss-style.xsl -->
<style type="text/css">
body{color:oklch(25% 0.005 298)} /* font color */
.bg-white{background-color:oklch(0.96 0.005 298)!important} /* background color */
.text-gray{color:oklch(0.25 0.005 298 / 75%)!important} /* secondary font color */
body{color:oklch(25% 0.005 298)} /* Font color */
.bg-white{background-color:oklch(0.96 0.005 298)!important} /* Background color */
.text-gray{color:oklch(0.25 0.005 298 / 75%)!important} /* Secondary font color */
</style>
```

View file

@ -75,12 +75,13 @@ global: {
// idioma de la ruta raíz del sitio '/'
locale: 'zh' // zh, zh-tw, ja, en, es, ru
// más idiomas
// Genera rutas multilingües como '/es/' '/ru/'
// no incluir el idioma predeterminado nuevamente, puede ser un array vacío []
// genera rutas multilingües como '/es/' '/ru/'
// no incluir el código de idioma anterior nuevamente, puede ser un array vacío []
moreLocales: ['zh-tw', 'ja', 'en', 'es', 'ru'] // ['zh', 'zh-tw', 'ja', 'en', 'es', 'ru']
// estilo de fuente
fontStyle: 'sans' // sans, serif
// formato de fecha para publicaciones
// 2025-04-13, 04-13-2025, 13-04-2025, Mar 13 2025, 13 Mar 2025
dateFormat: 'YYYY-MM-DD' // YYYY-MM-DD, MM-DD-YYYY, DD-MM-YYYY, MONTH DAY YYYY, DAY MONTH YYYY
// habilitar KaTeX para renderizar fórmulas matemáticas
katex: true // true, false
@ -205,11 +206,11 @@ Temas de resaltado de sintaxis para bloques de código.
// astro.config.ts
shikiConfig: {
// temas disponibles: https://shiki.style/themes
// el color de fondo sigue el tema del blog por defecto, no el tema de resaltado de sintaxis
// Temas disponibles: https://shiki.style/themes
// El color de fondo sigue el tema del blog por defecto, no el tema de resaltado de sintaxis
themes: {
light: 'github-light' // tema claro
dark: 'github-dark' // tema oscuro
light: 'github-light' // Tema claro
dark: 'github-dark' // Tema oscuro
}
}
```
@ -241,23 +242,23 @@ Estilos de imágenes sociales Open Graph.
getImageOptions: (_path, page) => ({
logo: {
path: './public/icon/og-logo.png', // ruta local requerida y formato PNG
size: [250], // ancho del logo
path: './public/icon/og-logo.png', // Ruta local requerida y formato PNG
size: [250], // Ancho del logo
},
font: {
title: { // título
families: ['Noto Sans SC'], // fuente
weight: 'Bold', // peso
color: [34, 33, 36], // color
lineHeight: 1.5, // altura de línea
title: { // Título
families: ['Noto Sans SC'], // Fuente
weight: 'Bold', // Peso
color: [34, 33, 36], // Color
lineHeight: 1.5, // Altura de línea
},
},
fonts: [ // rutas de fuentes (locales o remotas)
'https://raw.githubusercontent.com/notofonts/noto-cjk/main/Sans/SubsetOTF/SC/NotoSansSC-Bold.otf',
'https://raw.githubusercontent.com/notofonts/noto-cjk/main/Sans/SubsetOTF/SC/NotoSansSC-Regular.otf',
fonts: [ // Rutas de fuentes (locales o remotas)
'https://cdn.jsdelivr.net/gh/notofonts/noto-cjk@main/Sans/SubsetOTF/SC/NotoSansSC-Bold.otf',
'https://cdn.jsdelivr.net/gh/notofonts/noto-cjk@main/Sans/SubsetOTF/SC/NotoSansSC-Regular.otf',
],
bgGradient: [[242, 241, 245]], // color de fondo
// más configuraciones: https://github.com/delucis/astro-og-canvas/tree/latest/packages/astro-og-canvas
bgGradient: [[242, 241, 245]], // Color de fondo
// Más configuraciones: https://github.com/delucis/astro-og-canvas/tree/latest/packages/astro-og-canvas
})
```
@ -269,9 +270,9 @@ Estilos de página del feed RSS.
<!-- public/rss/rss-style.xsl -->
<style type="text/css">
body{color:oklch(25% 0.005 298)} /* color de fuente */
.bg-white{background-color:oklch(0.96 0.005 298)!important} /* color de fondo */
.text-gray{color:oklch(0.25 0.005 298 / 75%)!important} /* color de fuente secundario */
body{color:oklch(25% 0.005 298)} /* Color de fuente */
.bg-white{background-color:oklch(0.96 0.005 298)!important} /* Color de fondo */
.text-gray{color:oklch(0.25 0.005 298 / 75%)!important} /* Color de fuente secundario */
</style>
```

View file

@ -81,6 +81,7 @@ global: {
// フォントスタイル
fontStyle: 'sans' // sans, serif
// 記事の日付フォーマット
// 2025-04-13, 04-13-2025, 13-04-2025, Mar 13 202513 Mar 2025
dateFormat: 'YYYY-MM-DD' // YYYY-MM-DD, MM-DD-YYYY, DD-MM-YYYY, MONTH DAY YYYY, DAY MONTH YYYY
// 数式表示のためのKaTeXを有効化
katex: true // true, false
@ -253,8 +254,8 @@ getImageOptions: (_path, page) => ({
},
},
fonts: [ // フォントパス(ローカルまたはリモート)
'https://raw.githubusercontent.com/notofonts/noto-cjk/main/Sans/SubsetOTF/SC/NotoSansSC-Bold.otf',
'https://raw.githubusercontent.com/notofonts/noto-cjk/main/Sans/SubsetOTF/SC/NotoSansSC-Regular.otf',
'https://cdn.jsdelivr.net/gh/notofonts/noto-cjk@main/Sans/SubsetOTF/SC/NotoSansSC-Bold.otf',
'https://cdn.jsdelivr.net/gh/notofonts/noto-cjk@main/Sans/SubsetOTF/SC/NotoSansSC-Regular.otf',
],
bgGradient: [[242, 241, 245]], // 背景色
// その他の設定: https://github.com/delucis/astro-og-canvas/tree/latest/packages/astro-og-canvas

View file

@ -75,12 +75,13 @@ global: {
// язык корневого пути сайта '/'
locale: 'zh' // zh, zh-tw, ja, en, es, ru
// дополнительные языки
// Создает многоязычные пути, такие как '/es/' '/ru/'
// не указывайте повторно язык по умолчанию, можно оставить пустым массивом []
// создает многоязычные пути, такие как '/es/' '/ru/'
// не указывайте код языка, указанный выше, можно оставить пустым массивом []
moreLocales: ['zh-tw', 'ja', 'en', 'es', 'ru'] // ['zh', 'zh-tw', 'ja', 'en', 'es', 'ru']
// стиль шрифта
fontStyle: 'sans' // sans, serif
// формат даты для постов
// 2025-04-13, 04-13-2025, 13-04-2025, Мар 13 2025, 13 Мар 2025
dateFormat: 'YYYY-MM-DD' // YYYY-MM-DD, MM-DD-YYYY, DD-MM-YYYY, MONTH DAY YYYY, DAY MONTH YYYY
// включить KaTeX для отображения математических формул
katex: true // true, false
@ -205,11 +206,11 @@ preload: {
// astro.config.ts
shikiConfig: {
// доступные темы: https://shiki.style/themes
// цвет фона по умолчанию следует теме блога, а не теме подсветки синтаксиса
// Доступные темы: https://shiki.style/themes
// Цвет фона по умолчанию следует теме блога, а не теме подсветки синтаксиса
themes: {
light: 'github-light' // светлая тема
dark: 'github-dark' // темная тема
light: 'github-light' // Светлая тема
dark: 'github-dark' // Темная тема
}
}
```
@ -241,23 +242,23 @@ const EXCERPT_LENGTHS: Record<ExcerptScene, {
getImageOptions: (_path, page) => ({
logo: {
path: './public/icon/og-logo.png', // требуется локальный путь и формат PNG
size: [250], // ширина логотипа
path: './public/icon/og-logo.png', // Требуется локальный путь и формат PNG
size: [250], // Ширина логотипа
},
font: {
title: { // заголовок
families: ['Noto Sans SC'], // шрифт
weight: 'Bold', // вес
color: [34, 33, 36], // цвет
lineHeight: 1.5, // высота строки
title: { // Заголовок
families: ['Noto Sans SC'], // Шрифт
weight: 'Bold', // Вес
color: [34, 33, 36], // Цвет
lineHeight: 1.5, // Высота строки
},
},
fonts: [ // пути к шрифтам (локальные или удаленные)
'https://raw.githubusercontent.com/notofonts/noto-cjk/main/Sans/SubsetOTF/SC/NotoSansSC-Bold.otf',
'https://raw.githubusercontent.com/notofonts/noto-cjk/main/Sans/SubsetOTF/SC/NotoSansSC-Regular.otf',
fonts: [ // Пути к шрифтам (локальные или удаленные)
'https://cdn.jsdelivr.net/gh/notofonts/noto-cjk@main/Sans/SubsetOTF/SC/NotoSansSC-Bold.otf',
'https://cdn.jsdelivr.net/gh/notofonts/noto-cjk@main/Sans/SubsetOTF/SC/NotoSansSC-Regular.otf',
],
bgGradient: [[242, 241, 245]], // цвет фона
// дополнительные настройки: https://github.com/delucis/astro-og-canvas/tree/latest/packages/astro-og-canvas
bgGradient: [[242, 241, 245]], // Цвет фона
// Дополнительные настройки: https://github.com/delucis/astro-og-canvas/tree/latest/packages/astro-og-canvas
})
```
@ -269,92 +270,8 @@ getImageOptions: (_path, page) => ({
<!-- public/rss/rss-style.xsl -->
<style type="text/css">
body{color:oklch(25% 0.005 298)} /* цвет шрифта */
.bg-white{background-color:oklch(0.96 0.005 298)!important} /* цвет фона */
.text-gray{color:oklch(0.25 0.005 298 / 75%)!important} /* вторичный цвет шрифта */
body{color:oklch(25% 0.005 298)} /* Цвет шрифта */
.bg-white{background-color:oklch(0.96 0.005 298)!important} /* Цвет фона */
.text-gray{color:oklch(0.25 0.005 298 / 75%)!important} /* Вторичный цвет шрифта */
</style>
```
## Создание Новой Статьи
Создайте новый файл с расширением `.md` или `.mdx` в директории `src/content/posts/` и добавьте метаданные `Front Matter` в верхней части файла.
### Front Matter
```markdown
---
# Обязательно
title: Руководство по теме
published: 2025-01-26
# Опционально
description: Первые 240 символов статьи будут автоматически выбраны в качестве выдержки.
updated: 2025-03-26
tags:
- Тема блога
- Руководство
# Расширенные настройки, Опционально
draft: true/false
pin: 1-99
toc: true/false
lang: en/es/ru/zh/zh-tw/ja
abbrlink: theme-guide
---
```
### Расширенная Конфигурация
#### draft
Помечает статью как черновик. Если установлено значение true, статья не может быть опубликована и доступна только для предварительного просмотра при локальной разработке. По умолчанию - false.
#### pin
Закрепляет статью вверху. Чем выше число, тем выше приоритет закрепленной статьи. По умолчанию - 0, что означает отсутствие закрепления.
#### toc
Генерировать оглавление. Показывает заголовки от h2 до h4. По умолчанию: true.
#### lang
Указывает язык статьи. Можно указать только один язык. Если не указано, статья будет отображаться во всех языковых путях по умолчанию.
```md
# src/config.ts
# locale: 'en'
# moreLocales: ['es', 'ru']
# lang: ''
src/content/posts/apple.md -> example.com/posts/apple/
-> example.com/es/posts/apple/
-> example.com/ru/posts/apple/
# lang: en
src/content/posts/apple.md -> example.com/posts/apple/
# lang: es
src/content/posts/apple.md -> example.com/es/posts/apple/
# lang: ru
src/content/posts/apple.md -> example.com/ru/posts/apple/
```
#### abbrlink
Настраивает URL статьи. Может содержать только строчные буквы, цифры и дефисы `-`.
```md
# src/config.ts
# locale: 'en'
# moreLocales: ['es', 'ru']
# lang: 'es'
# abbrlink: ''
src/content/posts/apple.md -> example.com/es/posts/apple/
src/content/posts/guide/apple.md -> example.com/es/posts/guide/apple/
src/content/posts/2025/03/apple.md -> example.com/es/posts/2025/03/apple/
# abbrlink: 'banana'
src/content/posts/apple.md -> example.com/es/posts/banana/
src/content/posts/guide/apple.md -> example.com/es/posts/banana/
src/content/posts/2025/03/apple.md -> example.com/es/posts/banana/
```

View file

@ -81,6 +81,7 @@ global: {
// 字體樣式
fontStyle: 'sans' // sans, serif
// 文章日期格式
// 2025-04-13, 04-13-2025, 13-04-2025, Mar 13 202513 Mar 2025
dateFormat: 'YYYY-MM-DD' // YYYY-MM-DD, MM-DD-YYYY, DD-MM-YYYY, MONTH DAY YYYY, DAY MONTH YYYY
// 啟用 KaTeX 數學公式渲染
katex: true // true, false
@ -253,8 +254,8 @@ getImageOptions: (_path, page) => ({
},
},
fonts: [ // 字體路徑(本地或遠程)
'https://raw.githubusercontent.com/notofonts/noto-cjk/main/Sans/SubsetOTF/SC/NotoSansSC-Bold.otf',
'https://raw.githubusercontent.com/notofonts/noto-cjk/main/Sans/SubsetOTF/SC/NotoSansSC-Regular.otf',
'https://cdn.jsdelivr.net/gh/notofonts/noto-cjk@main/Sans/SubsetOTF/SC/NotoSansSC-Bold.otf',
'https://cdn.jsdelivr.net/gh/notofonts/noto-cjk@main/Sans/SubsetOTF/SC/NotoSansSC-Regular.otf',
],
bgGradient: [[242, 241, 245]], // 背景色
// 更多配置https://github.com/delucis/astro-og-canvas/tree/latest/packages/astro-og-canvas

View file

@ -81,6 +81,7 @@ global: {
// 字体样式
fontStyle: 'sans' // sans, serif
// 文章日期格式
// 2025-04-13, 04-13-2025, 13-04-2025, Mar 13 202513 Mar 2025
dateFormat: 'YYYY-MM-DD' // YYYY-MM-DD, MM-DD-YYYY, DD-MM-YYYY, MONTH DAY YYYY, DAY MONTH YYYY
// 启用 KaTeX 数学公式渲染
katex: true // true, false
@ -253,8 +254,8 @@ getImageOptions: (_path, page) => ({
},
},
fonts: [ // 字体路径(本地或远程)
'https://raw.githubusercontent.com/notofonts/noto-cjk/main/Sans/SubsetOTF/SC/NotoSansSC-Bold.otf',
'https://raw.githubusercontent.com/notofonts/noto-cjk/main/Sans/SubsetOTF/SC/NotoSansSC-Regular.otf',
'https://cdn.jsdelivr.net/gh/notofonts/noto-cjk@main/Sans/SubsetOTF/SC/NotoSansSC-Bold.otf',
'https://cdn.jsdelivr.net/gh/notofonts/noto-cjk@main/Sans/SubsetOTF/SC/NotoSansSC-Regular.otf',
],
bgGradient: [[242, 241, 245]], // 背景色
// 更多配置https://github.com/delucis/astro-og-canvas/tree/latest/packages/astro-og-canvas