Render components such as callouts, timelines, charts, galleries and kanban boards with `:::` Markdown directives, with no need to write components or CSS
AstroBlogDocumentation
vergil-astro-theme — Astro Blog Template
By vergil-astro
An Astro-based blog and documentation theme that renders callouts, timelines, charts, galleries and other components via Markdown directives, with no need to write components or CSS.
Explore the design
Compare the page layouts and mobile experience. Open any screenshot for a closer look.
Desktop homepage1 / 3
Desktop captureTop of page
Actual screenshot captured by the server browser.
All pages & views 3
Screenshots show visual appearance; interactive behavior may differ.
Recorded 2026-10-07View source
What stands out
A quick read of the recorded project description.
51 directives in total, divided into eight categories: structural layout, content display, media embedding, cards and links, text and interaction, chart visualization, time planning, and visual storytelling
Provides three independent layouts and navigations: default view, minimal mode and resume mode
Content organization supports free combination of four dimensions: tags, categories, columns and hierarchical docs
Galleries include two themes, Golden and Seasons, with Lightbox, EXIF information and season filtering
Built-in dark mode, full-text search, comments, RSS, Sitemap and site assistant, with interface text switchable between Chinese and English
Template Details
Vergil is an Astro-based content site theme aimed at two scenarios: blogs and documentation. Its core approach is to turn common content components into Markdown directives: writing a directive starting with `:::` in Markdown renders elements such as callouts, timelines, charts, galleries and kanban boards, without writing separate components or adjusting CSS. The repository documentation lists 51 directives in total, grouped by purpose into eight categories: structural layout, content display, media embedding, cards and links, text and interaction, chart visualization, time planning, and visual storytelling; math formulas are written directly with `$...$` and do not count as directives.
Beyond directives, the theme also provides multiple views (default view, minimal mode, resume mode, each with its own layout and navigation), content organization dimensions (tags, categories, columns, hierarchical docs), two gallery themes (Golden and Seasons, with Lightbox, EXIF information and season filtering), pluggable left and right sidebar components (heatmap, tag cloud, table of contents, related articles), and site features such as dark mode, full-text search, comments, RSS, Sitemap and a site assistant. Interface text supports switching between Chinese and English without affecting user-written content.
Before use, note the following: the articles, galleries and sample docs included in the repository are all demo content, and official `pnpm reset` commands are provided for cleanup, where `pnpm reset` keeps the theme's built-in usage documentation, while `pnpm reset:all` deletes it as well. Complete configuration and writing instructions are under the `/docs` path after the site starts, with source files in `src/content/docs/vergil-guide/`. The project is maintained by an individual in their spare time, and the code uses the MIT license, but third-party assets such as demo images, fonts and icons need to be checked separately under their respective licenses.
AstroBlogDocumentation
Is it right for your project?
Use Cases
- Building a personal blog focused on Markdown writing that needs layout elements such as callouts, timelines and charts
- Creating a knowledge base or product documentation site with a hierarchical docs tree and sidebar table of contents
- Making photography gallery pages with EXIF information and season filtering
- Presenting a personal resume page with resume mode
- Configuring multi-dimensional content organization such as tags, categories and columns for a content site
Suitable For
- Content creators who are used to writing in Markdown and do not want to hand-write components or adjust CSS
- Sites that need to host both blog and documentation content
- Projects that want to quickly insert visual elements such as charts, timelines and galleries via directives
- Developers who accept an open-source theme maintained by an individual and released under the MIT license
Getting started & customization
Use these recorded setup notes alongside the repository instructions for your chosen version.
- 1
Requires Node.js 22 (the version used in CI) and pnpm
- 2
After cloning the repository, run pnpm install and pnpm dev to start local development
- 3
The articles, galleries and sample docs included in the repository are demo content; use pnpm reset:dry to preview and pnpm reset to clean up; pnpm reset keeps the theme usage documentation, while pnpm reset:all deletes it as well
- 4
Complete configuration and writing instructions are under the /docs path after the site starts, with source files in src/content/docs/vergil-guide/
- 5
The code uses the MIT license, but third-party assets such as demo images, fonts and icons need to be checked separately under their respective licenses
License & source material
Usage conditions & limitations
Free to use · keep license noticeThis entry covers the free version in the public repository under the MIT license; the free scope is the code of this version and does not mean that external services or third-party assets are free.
Must comply with when using
- Allows free use, modification, commercial use and distribution of this version's code.
- When distributing copies or substantial portions of the code, retain the original author's copyright notice and the complete MIT license notice.
- The code is provided as is; warranties and limitations of liability are governed by the original license and applicable law.
Additional costs & items to verify
- Demo images, fonts, icons and other third-party assets need to be checked under their respective licenses and cannot be judged solely by the code's MIT license.
- External services such as domains, hosting, databases, payments or AI may incur additional charges.
- The articles, galleries and sample docs included in the repository are all demo content and need to be cleaned up or replaced before formal use.
- The cleanup command pnpm reset keeps the theme's built-in usage documentation; to delete it as well, use pnpm reset:all instead.
- The runtime environment requires Node.js 22 and pnpm; builds may fail if the versions do not match.
View Original Text Basis
Permission is hereby granted, free of charge
Original License Text
The posts, galleries, and sample documents included in the repository are demo content.
Original README
`pnpm reset` keeps the built-in Vergil documentation for future reference. To remove it as well, use `pnpm reset:all`.
Original README
https://github.com/vergil-astro/vergil-astro-theme/blob/main/LICENSEhttps://github.com/vergil-astro/vergil-astro-theme/blob/main/README.mdRequires Node.js 22 (the version used in CI) and pnpm.
Original README
Compiled by DeepSeek based on repository license and README ·2026-10-07. Results only cover the materials read; dependencies, images, fonts, and subsequent term changes are subject to their respective original texts.
Project checks & description sources
Template Information
- Source platforms
- GitHub
- Documentation and maintenance reference score
- More documented · 85 / 100
- Technologies
- Astro
- Website type
- Blog · Documentation
How this score is calculated
Our heuristic uses license records (up to 30), a demo link (12), a preview (10), stars (15), recorded maintenance (15), description completeness (8), feature records (5) and classification data (5). It is not a code, security or performance test, or a Google score. A link does not establish tested functionality.
What to verify for this project
- Repository update recorded
- 2026-10-07
- Screenshot last checked
- 2026-10-07
A demo link is listed. Check it with your own content and viewport sizes; its presence does not confirm that forms, authentication or payments work.
The catalog identifies Astro as the primary stack. Check the actual dependency manifest and lockfile for versions and hosting requirements. These notes use recorded metadata, not a code audit or a deployment test.
Use a selection guide →How this description was prepared
AI-assisted description based on catalog records and repository material. Repository authors are not automatically the reviewers of this description.
Review declaration: [email protected] · 2026-10-07
Inspect the recorded source material
SHA-256: 205e8436e2f910edb25095c34aca7a41521bba83fffb912dad8c56bb0ee43d58
2026-10-07T10:01:06.557Z
Source file / repository<div align="center">
<img src="public/favicon.svg" width="96" alt="Vergil">
# Vergil
</div>
<details>
<summary><a href="README_CN.md">简体中文</a>（点击展开 / 收起）</summary>
<div align="center">
**写 Markdown，剩下的交给主题。**
一套基于 Astro 的内容站点框架。提示框、时间线、图表、相册、看板这些东西都做成了 Markdown 指令，不用写组件，不用碰 CSS。
[](https://astro.build)
[](https://tailwindcss.com)
[](https://www.typescriptlang.org)
[](LICENSE)
[](https://github.com/vergil-astro/vergil-astro-theme)
</div>
## 快速开始
需要 Node.js 22（CI 上用的版本）和 pnpm。
```bash
git clone https://github.com/vergil-astro/vergil-astro-theme.git
cd vergil-astro-theme
pnpm install
pnpm dev
```
仓库自带的文章、相册、示例文档是演示内容。确认能跑起来之后，清掉它们：
```bash
pnpm reset:dry # 先看会删什么
pnpm reset # 确认后真正清理
```
`pnpm reset` 会保留站内的 Vergil 使用文档，那是你之后要查的东西。想一起删掉用 `pnpm reset:all`。
## 它能做什么
写一段 `:::` 指令，得到一个组件：
```markdown
:::callout{type="tip"}
这是一条小技巧，读者一眼就能注意到。
:::
:::timeline
- 2024-01 | 项目启动
- 2024-06 | 第一个版本
:::
:::video{bilibili="BV1xx411c7mD"}
:::
```
一共 51 个指令，按用途分为八类：结构排版、内容展示、媒体嵌入、卡片与链接、文字与交互、图表可视化、时间规划、可视化叙事。数学公式用 `$...$` 直接写，不需要指令。
除了指令，Vergil 还提供这些：
| | |
|---|---|
| **多视图** | 默认视图、极简模式、简历模式，各自独立的布局和导航 |
| **内容组织** | 标签、分类、专栏、层级文档，四个维度自由组合 |
| **相册** | Golden 与 Seasons 两套主题，Lightbox、EXIF 信息、季节过滤 |
| **侧边栏** | 左右侧栏组件可插拔，热力图、标签云、目录、相关文章 |
| **开箱即用** | 深色模式、全文搜索、评论、RSS、Sitemap、站点助理 |
| **界面语言** | 主题文案支持中英切换，你写的内容不受影响 |
四格分别是：文章里的折叠块与时间线指令、Golden 主题的影集、带侧边目录树的知识库、按分类筛选的极简模式。
具体怎么配、怎么写，跑起来之后站内的 `/docs` 就是完整文档，源文件在 [`src/content/docs/vergil-guide/`](src/content/docs/vergil-guide)。
## 生态工具
- **[vergil-cli](https://github.com/vergil-astro/vergil-cli)** — 命令行工具 `vg`，初始化项目、新建文章相册动态、发布草稿
- **[vergil-writing-skills](https://github.com/vergil-astro/vergil-writing-skills)** — AI 写作技能，让助手用 Vergil 指令帮你排版，支持 Claude Code、Codex CLI、Cursor、Gemini CLI
## 参与贡献
Vergil 由个人在业余时间维护，欢迎提 Bug、聊想法、改文档、翻译界面文字。
改代码之前建议先开一个 [issue](https://github.com/vergil-astro/vergil-astro-theme/issues) 聊聊思路，免得白写。提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/)。
接下来要做什么、已经在做什么，都在 [issues](https://github.com/vergil-astro/vergil-astro-theme/issues) 里。
## 关于名字
Vergil 基于极简主题 [Dante](https://github.com/JustGoodUI/dante-astro-theme) 做了大量改造。名字致敬但丁的老对手，也代表这个项目从极简出发、走向体系化的方向。
## 致谢
- [Dante](https://github.com/JustGoodUI/dante-astro-theme) — Vergil 的起点
- [Hexo Stellar](https://github.com/xaoxuu/hexo-theme-stellar) — 标签体系与文档系统的设计灵感
- [Astro](https://astro.build) — 让静态站点开发重新变得有趣
## License
[MIT](LICENSE)
</details>
<details open>
<summary>English (click to collapse / expand)</summary>
<div align="center">
**Write Markdown. Let the theme handle the rest.**
A content site framework built on Astro. Callouts, timelines, charts, galleries, and kanban boards are all available as Markdown directives—no components to write or CSS to touch.
[](https://astro.build)
[](https://tailwindcss.com)
[](https://www.typescriptlang.org)
[](LICENSE)
[](https://github.com/vergil-astro/vergil-astro-theme)
</div>
## Quick Start
Requires Node.js 22 (the version used in CI) and pnpm.
```bash
git clone https://github.com/vergil-astro/vergil-astro-theme.git
cd vergil-astro-theme
pnpm install
pnpm dev
```
The posts, galleries, and sample documents included in the repository are demo content. Once the site is running, you can remove them:
```bash
pnpm reset:dry # Preview what will be removed
pnpm reset # Remove it after reviewing the preview
```
`pnpm reset` keeps the built-in Vergil documentation for future reference. To remove it as well, use `pnpm reset:all`.
## Features
Write a `:::` directive to render a component:
```markdown
:::callout{type="tip"}
Here's a quick tip your readers can spot at a glance.
:::
:::timeline
- 2024-01 | Project kickoff
- 2024-06 | First release
:::
:::video{bilibili="BV1xx411c7mD"}
:::
```
There are 51 directives across eight categories: structure and layout, content display, media embeds, cards and links, text and interaction, charts and visualization, time planning, and visual storytelling. Write math formulas directly with `$...$`—no directive needed.
Beyond directives, Vergil also includes:
| | |
|---|---|
| **Multiple views** | Default, immersive reading, and resume modes, each with its own layout and navigation |
| **Content organization** | Mix and match tags, categories, series, and hierarchical documentation |
| **Galleries** | Golden and Seasons themes, with a lightbox, EXIF metadata, and seasonal filtering |
| **Sidebars** | Pluggable components on both sides: heatmaps, tag clouds, table of contents, and related posts |
| **Ready to use** | Dark mode, full-text search, comments, RSS, sitemap, and a site assistant |
| **Interface language** | Switch theme text between English and Chinese without affecting your content |
The four panels show collapsible blocks and timeline directives in a post, a Golden-themed gallery, a knowledge base with a sidebar document tree, and an immersive reading view filtered by category.
For configuration and writing instructions, visit `/docs` after starting the site. The full documentation source is in [`src/content/docs/vergil-guide/`](src/content/docs/vergil-guide).
## Ecosystem Tools
- **[vergil-cli](https://github.com/vergil-astro/vergil-cli)** — The `vg` command-line tool for initializing projects, creating posts, galleries, and updates, and publishing drafts
- **[vergil-writing-skills](https://github.com/vergil-astro/vergil-writing-skills)** — AI writing skills that help assistants format your content with Vergil directives. Supports Claude Code, Codex CLI, Cursor, and Gemini CLI
## Contributing
Vergil is maintained by one person in their spare time. Bug reports, ideas, documentation improvements, and interface translations are welcome.
Before making code changes, consider opening an [issue](https://github.com/vergil-astro/vergil-astro-theme/issues) to discuss your approach and avoid wasted effort. Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/).
Planned and ongoing work is tracked in [issues](https://github.com/vergil-astro/vergil-astro-theme/issues).
## About the Name
Vergil extensively reworks the minimalist [Dante](https://github.com/JustGoodUI/dante-astro-theme) theme. The name pays homage to Dante's longtime rival and reflects the project's journey from minimalism toward a more comprehensive framework.
## Acknowledgments
- [Dante](https://github.com/JustGoodUI/dante-astro-theme) — Vergil's starting point
- [Hexo Stellar](https://github.com/xaoxuu/hexo-theme-stellar) — Inspiration for the tag and documentation systems
- [Astro](https://astro.build) — Making static site development fun again
## License
[MIT](LICENSE)
</details>
Explore similar templates
Compare previews and descriptions within the same stack and category.
astrowind
AstroWind is a free, open-source Astro starter theme using Astro and Tailwind CSS, released under the MIT license.
Astro · Blog
astro-paper
AstroPaper is a minimal, responsive, accessible, and SEO-friendly Astro blog theme. Articles are stored as Markdown/MDX in src/content/posts/, with subdirectories affecting URLs.
Astro · Blog
fuwari
Fuwari is a static blog template built with Astro and Tailwind CSS for personal blogs. It manages posts as Markdown files in src/content/posts/, with frontmatter for title, date, description, cover, tags, categories, draft status, and language.
Astro · Blog
Firefly
Firefly is a clean personal blog theme forked from Astro and Fuwari, offering four background modes, single/double sidebar and list/grid layouts, Pagefind client-side full-text search, and a six-language UI.
Astro · Blog
astro-theme-cactus
Astro Cactus is an Astro-based blog and portfolio theme that uses Markdown/MDX content collections to manage posts, notes, and tags, with frontmatter type-checked by a schema.
Astro · Portfolio
astrofy
Astrofy is a free and open-source personal portfolio website template built with Astro and TailwindCSS, with built-in blog, CV timeline, project showcase, store, and RSS feed modules.
Astro · Portfolio