FlexSearch-based full-text search in Chinese and English, with a three-column layout integrating results, previews, and scroll markers, and support for filtering by date, tags, and type
AstroBlog
astro-theme-iris — Astro Blog Template
By LemonAdorable
An Astro-based blog and knowledge base theme customized from astro-theme-pure, integrating full-text search, Wikilink previews, and a knowledge graph.
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-02View source
What stands out
A quick read of the recorded project description.
Wikilink multi-level nested previews via Tippy.js, with backlink positioning
Knowledge graph drawn with D3.js, distinguishing article, document, tag, and category nodes, with switchable local and global views
Integrated Giscus comments, Mermaid diagrams, and Typst mathematical formula and graphic rendering in MDX
Customized from astro-theme-pure, with main configuration centralized in src/site.config.ts
Template Details
Astro Theme Iris is a blog and documentation theme built with Astro, positioned by its author as a personal knowledge management system that combines a blog, personal profile, and knowledge base. The project is customized from astro-theme-pure, the repository uses the Apache-2.0 license, and the demo site is https://lemonadorable.github.io/.
The theme's core capabilities focus on knowledge organization and retrieval: search uses FlexSearch for full-text search in Chinese and English, with a three-column layout that places search results, content previews, and scroll markers together, and supports filtering by date range, tags, and type (article/document). Wikilinks use Tippy.js to provide Quartz-like multi-level nested previews and support backlink positioning. The knowledge graph uses D3.js to draw a directed graph, distinguishing node types such as articles, documents, tags, and categories; it can switch between a local graph for the current page and a global graph for the entire site, and supports dragging, zooming, and click-through navigation. It also integrates Giscus comments (based on GitHub Discussions), Mermaid diagrams, and Typst for rendering mathematical formulas and graphics in MDX.
For usage, the README recommends creating a repository via GitHub's Use this template button, and also supports cloning and then installing dependencies locally to run. The main configuration file is located at src/site.config.ts, where site information, social links, and the comment system can be set. Important limitations: the author explicitly notes that the project is still changing frequently, and when pulling updates, do not use git pull directly; instead, use git fetch plus git merge --no-commit to manually review the merge result. The header and customization options are still under development; the to-do list includes multilingual support, a homepage resume feature, theme packaging, and more documentation examples, which are not yet complete.
AstroBlog
Is it right for your project?
Use Cases
- Building a personal knowledge base or digital garden with full-text search and bidirectional links
- Managing blog posts and documentation content together on one site
- Adding a visual knowledge graph and page relationship browsing to a notes site
- Rendering mathematical formulas, graphics, and Mermaid flowcharts in MDX content
Suitable For
- Blog or knowledge base authors using Astro who want to get started quickly with a template
- Sites that need knowledge organization features such as Chinese and English full-text search, Wikilink previews, and a knowledge graph
- Developers who can accept frequent project changes and are willing to manually review merged updates
Getting started & customization
Use these recorded setup notes alongside the repository instructions for your chosen version.
- 1
Recommended: create a repository on GitHub via the Use this template button and then clone it locally; cloning the repository directly is also supported
- 2
Install dependencies and start development: bun install or npm install, then bun dev or npm run dev
- 3
The main configuration file is src/site.config.ts, where basic site information, social links, and the comment system can be set
- 4
The author advises against using git pull directly when updating; use git fetch plus git merge --no-commit to manually review the merge result
- 5
The header and customization options are still under development; multilingual support, the homepage resume feature, and theme packaging are not yet complete
License & source material
Usage conditions & limitations
Free to use · keep license noticeThis entry covers the free version in the public repository under the Apache-2.0 license; the free scope is the code of that version and does not imply that external services or third-party assets are free.
Must comply with when using
- Free use, modification, commercial use, and distribution are permitted; when distributing, include the Apache-2.0 license.
- Modified files must prominently indicate changes and retain relevant copyright, patent, trademark, and attribution notices.
- If the original project includes a NOTICE file, applicable attribution notices in it must be retained when distributing derivative works.
- The license includes an applicable contributor patent grant; initiating patent litigation as described in the license terminates that patent grant, and no trademark use rights are granted.
- 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
- The author requires that when updating the theme, do not use git pull directly; instead, use git fetch plus git merge --no-commit to manually review and control the merge result, so that automatic merging does not overwrite local customizations.
- The header and customization options are still under development; related features are incomplete, and this part may be unstable or unfinished.
- Multilingual support is not yet complete and is still listed as an unimplemented feature in the current to-do list; the site is mainly oriented toward Chinese content.
- The homepage resume feature has not been implemented and is a to-do item; it cannot be relied upon as a site capability.
- Theme packaging and new components are not yet complete and are to-do items; no packaged theme distribution form is currently provided.
- More documentation and examples are not yet provided and are to-do items; the documentation and examples available for reference are limited.
- Demo images, fonts, icons, and other third-party assets must be checked against their respective licenses; they cannot be judged solely by the code's Apache-2.0 license.
- External services such as domains, hosting, databases, payments, or AI may incur additional charges.
View Original Text Basis
no-charge, royalty-free, irrevocable copyright license
Original License Text
When pulling updates, please do not use `git pull` directly. Instead, use `git fetch` + `git merge --no-commit` to manually review and control the merge results.
Original README
Known issues: Header & customize options is still under development (template exposed still).
Original README
- [ ] English or multi-language support
Original README
- [ ] Homepage resume feature
Original README
- [ ] Package theme and new components
Original README
https://github.com/LemonAdorable/astro-theme-iris/blob/main/LICENSEhttps://github.com/LemonAdorable/astro-theme-iris/blob/main/README.md- [ ] More documentation and examples
Original README
Compiled by DeepSeek based on repository license and README ·2026-10-02. 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 · 87 / 100
- Technologies
- Astro
- Website type
- Blog
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-07-29
- Screenshot last checked
- 2026-10-02
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.
Automatically checked against source and license rules; no manual editorial review.
Inspect the recorded source material
SHA-256: 1acc38deb4d149ae22b589f364655131ad39ecaf4764a60a51054edd86951fb3
2026-10-02T16:47:42.070Z
Source file / repository# Astro Theme Iris
English | [简体中文](./README-zh-CN.md)
> [!CAUTION]
> This project is undergoing frequent changes, and automatic merging may overwrite your local customizations. When pulling updates, please do not use `git pull` directly. Instead, use `git fetch` + `git merge --no-commit` to manually review and control the merge results.
<div align="center">
<img src="./logo.png" alt="Astro Theme Iris Logo" width="200">
</div>
---
## 📸 Screenshots
**Demo Blog**: [https://lemonadorable.github.io/](https://lemonadorable.github.io/)
> [!NOTE]
> Known issues: Header & customize options is still under development (template exposed still).
<div align="center">
<img src="./index.png" alt="Homepage Showcase" width="100%">
<p><em>Full-screen homepage with animation effects</em></p>
</div>
<div align="center">
<img src="./search.png" alt="Search Feature Showcase" width="100%">
<p><em>Powerful search preview system - supports category filtering, real-time preview, and scroll markers</em></p>
</div>
<div align="center">
<img src="./function.png" alt="Feature Showcase" width="100%">
<p><em>Wikilink preview, Graph View, and knowledge graph</em></p>
</div>
---
## 🎨 About Iris Theme
This project is customized based on [astro-theme-pure](https://github.com/cworld1/astro-theme-pure), aiming to combine **blog**, **profile**, and **knowledge base** to create a powerful personal knowledge management system.
### ✨ Core Features
#### 🔍 Powerful Search System
- **FlexSearch Full-Text Search**: High-performance search supporting multiple languages including Chinese and English
- **Three-Column Preview Layout**: Integrated search results, content preview, and scroll markers
- **Multi-Dimensional Filtering**: Filter by date range, tags, and type (article/docs)
- **Real-Time Highlighting**: Real-time search result highlighting with scroll positioning
#### 🔗 Wikilink System
- **Multi-Level Preview**: Uses Tippy.js to implement Quartz-like multi-layer preview functionality
- **Smart Positioning**: Supports backlinks and reverse positioning references
- **Smooth Interaction**: Supports nested previews
#### 🗺️ Knowledge Graph (Graph View)
- **D3.js Directed Graph**: Visualizes relationships between pages
- **Local/Global Views**: View local graph for current page or site-wide global graph
- **Node Types**: Distinguishes between articles, docs, tags, categories, and other types
- **Interactive Operations**: Supports drag, zoom, and click navigation
#### 🎨 UI Optimization
- **Full-Screen Homepage**: Immersive homepage design with animation effects
- **Gradient Background**: Article cards use light purple gradient backgrounds
- **Interactive Animations**: Interactive animation effects for avatars and friend links
- **Responsive Design**: Adapted for desktop and mobile devices
#### 💬 Comment System
- **Giscus Integration**: Comment system based on GitHub Discussions
#### 📊 Mermaid Integration
- **Mermaid Integration**: Mermaid integration for diagramming
#### 🖋️ Typst Integration
- **Typst Support**: Typst integration for high-quality mathematical equations and diagrams rendering in MDX
### 🚀 Quick Start
#### Option 1: Use as a Template (Recommended)
1. Click the **"Use this template"** button at the top of this repository.
2. Clone your new repository to local.
3. Install dependencies and start developing:
```shell
bun install # or npm install
bun dev # or npm run dev
```
#### Option 2: Manual Installation
```shell
# Clone repository
git clone https://github.com/LemonAdorable/astro-theme-iris.git
cd astro-theme-iris
# Install dependencies
bun install # or npm install
```
### 🔄 Updating Theme
To get the latest features and fixes from the Iris theme:
```shell
# Add upstream remote (only need to do once)
git remote add upstream https://github.com/LemonAdorable/astro-theme-iris.git
# Pull and merge updates from main branch
git fetch upstream main
git merge upstream/main --allow-unrelated-histories
```
> [!TIP]
> The `--allow-unrelated-histories` flag is only required for the first merge if you have an existing repository with a different history. For future updates, a simple `git pull upstream main` will work.
### 📝 Todo
- [ ] English or multi-language support
- [ ] Homepage resume feature
- [ ] Package theme and new components
- [ ] More documentation and examples
### 📚 Repository Structure
```
Iris Theme (LemonAdorable/astro-theme-iris)
└── main branch (Upstream)
↓ (fetch & merge)
Your Blog Repository
└── main branch (Your content + Iris components)
```
### 🙏 Acknowledgments
This project is based on the following excellent open-source projects:
- **[astro-theme-pure](https://github.com/cworld1/astro-theme-pure)** - Base theme framework
- **[FlexSearch](https://github.com/nextapps-de/flexsearch)** - High-performance full-text search engine
- **[Tippy.js](https://atomiks.github.io/tippyjs/)** - Powerful tooltip library
- **[D3.js](https://d3js.org/)** - Data visualization library
- **[Quartz](https://quartz.jzhao.xyz/)** - Knowledge base theme design concept reference
- **[Obsidian](https://obsidian.md/)** - Wikilink note concept reference
### 📞 Contact
For questions or suggestions, please feel free to contact via email
### 📋 Usage Instructions
#### Search Feature
- Press `Ctrl+K` or `Cmd+K` to open the search box
- Supports Chinese and English full-text search
- Filter by date range, tags, and type
- Click search results to navigate to corresponding pages
- Right preview area supports scroll marker positioning
#### Wikilink Preview
- Use `[[link text]]` or `[[link|display text]]` in articles to create wikilinks
- Hover over wikilinks to preview link content
- Supports multi-level nested previews
- Preview box supports interaction, click links to navigate
#### Knowledge Graph
- Graph View displayed in sidebar on article and doc pages
- Click nodes to navigate to corresponding pages
- Supports dragging nodes to adjust layout
- Click top-right button to view site-wide global graph
### ⚙️ Configuration
Main configuration file is located at `src/site.config.ts`, where you can configure:
- Basic site information (title, description, author, etc.)
- Social links
- Comment system (Giscus/Waline)
- Other theme options
### 📄 License
This project is open source under the [Apache 2.0 License](https://github.com/LemonAdorable/astro-theme-iris/main/LICENSE).
### ⭐ Star History
[](https://star-history.com/#LemonAdorable/astro-theme-iris&Date)
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