176 lines
7.4 KiB
Markdown
176 lines
7.4 KiB
Markdown
# Astro Modular
|
|
|
|
A flexible [Astro](https://astro.build) blog theme designed for [Obsidian](https://obsidian.md) users.
|
|
|
|
[](https://astro.build/themes/details/astro-modular/)
|
|
|
|
## Made with Vault CMS
|
|
|
|
Use Obsidian as a CMS with [Vault CMS](https://github.com/davidvkimball/vault-cms).
|
|
|
|
|
|
|
|
## Stats
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Status
|
|
[](https://app.netlify.com/sites/astro-modular/deploys)
|
|
[](https://github.com/davidvkimball/astro-modular)
|
|
[](https://github.com/davidvkimball/astro-modular)
|
|
|
|
### Tech Stack
|
|
[](https://astro.build/)
|
|
[](https://www.typescriptlang.org/)
|
|
[](https://tailwindcss.com/)
|
|
[](https://nodejs.org/)
|
|
[](https://pnpm.io/)
|
|
[](https://obsidian.md/)
|
|
|
|
## Why Astro Modular?
|
|
|
|
- **Obsidian As A CMS**: Works with Obsidian out of the box (built upon [Vault CMS](https://github.com/davidvkimball/vault-cms)), write and publish instantly
|
|
- **Highly Customizable**: Every feature can be enabled/disabled independently
|
|
- **Performance-Focused**: Assets are highly optimized for lightning-fast loading
|
|
- **SEO-Ready**: Automatic sitemap, RSS feed, and Open Graph image generation
|
|
|
|
## Features
|
|
|
|
- [x] **Custom Themes**
|
|
- [x] **Feature Toggle Control**
|
|
- [x] **Dark/Light Mode**
|
|
- [x] **Search & Command Palette**
|
|
- [x] **Wikilinks & Linked Mentions**
|
|
- [x] **Obsidian-Style Callouts**
|
|
- [x] **Obsidian Embeds Files**
|
|
- [x] **Folder-Based Posts**
|
|
- [x] **Multiple Content Types**
|
|
- [x] **Image Optimization**
|
|
- [x] **Automatic Feed Generation**
|
|
- [x] **Table of Contents**
|
|
- [x] **Smooth Scroll & Page Transitions**
|
|
- [x] **Image Gallery & Lightbox**
|
|
- [x] **Reading Time & Word Count**
|
|
- [x] **Tagging**
|
|
- [x] **Graph View**
|
|
- [x] **Mermaid Diagrams**
|
|
- [x] **LaTeX & Math Rendering**
|
|
- [x] **Custom Typography**
|
|
- [x] **Profile Picture**
|
|
- [x] **Comments**
|
|
|
|
## Quick Start
|
|
|
|
[](https://app.netlify.com/start/deploy?repository=https://github.com/davidvkimball/astro-modular)
|
|
[](https://vercel.com/new/clone?repository-url=https://github.com/davidvkimball/astro-modular)
|
|
[](https://deploy.workers.cloudflare.com/?url=https://github.com/davidvkimball/astro-modular)
|
|
|
|
### Get the Code
|
|
|
|
Choose one of the following methods to get started:
|
|
|
|
#### Option 1: CLI (Recommended)
|
|
|
|
```bash
|
|
pnpm create astro-modular my-blog
|
|
cd my-blog
|
|
```
|
|
|
|
[](https://www.npmjs.com/package/create-astro-modular)
|
|
|
|
This downloads the latest template, removes dev-only files, and installs dependencies automatically. Also works with `npm create astro-modular my-blog`.
|
|
|
|
#### Option 2: Use GitHub Template
|
|
|
|
1. Click the **"Use this template"** button on the [repository page](https://github.com/davidvkimball/astro-modular)
|
|
2. Select **"Create a new repository"**
|
|
3. Choose your repository name and settings
|
|
4. Click **"Create repository from template"**
|
|
5. Clone your new repository:
|
|
```bash
|
|
git clone https://github.com/your-username/your-repo-name.git
|
|
cd your-repo-name
|
|
```
|
|
|
|
|
|
|
|
### Prerequisites
|
|
- Node.js 24.13.0+
|
|
- pnpm 10.29.3+ or npm 9.6.5+
|
|
|
|
> [!NOTE]
|
|
> While this theme works great with any markdown editor, it's specifically optimized for Obsidian use. See the [Astro Suite Vault Guide](src/content/posts/vault-cms-guide.md) for Obsidian-specific features.
|
|
|
|
### Setup
|
|
|
|
1. **Install pnpm (if you don't have it):**
|
|
```bash
|
|
npm install -g pnpm
|
|
```
|
|
|
|
2. **Install dependencies:**
|
|
```bash
|
|
pnpm install
|
|
```
|
|
|
|
3. **Preview:**
|
|
```bash
|
|
pnpm dev
|
|
```
|
|
Your blog will be available at `http://localhost:5000`
|
|
|
|
4. **Build for production:**
|
|
```bash
|
|
pnpm build
|
|
```
|
|
|
|
### Updating the theme
|
|
|
|
To pull the latest theme release (framework files, Astro, config) while keeping your content and assets:
|
|
|
|
```bash
|
|
pnpm run update
|
|
```
|
|
|
|
This downloads the latest release from GitHub, replaces framework files, restores your `src/content` and profile/favicon assets, then runs `pnpm install`. After updating, open Obsidian and use **Astro Modular Settings → Apply all settings** so your saved settings are written to the new `config.ts` if needed.
|
|
|
|
### Configuration
|
|
|
|
Edit `src/config.ts` to customize your site - change the theme, enable/disable features, and configure all settings.
|
|
|
|
## Deployment
|
|
|
|
Set your deployment platform once in `src/config.ts` under `deployment.platform` ("netlify", "vercel", "github-pages", or "cloudflare-workers"). The build process automatically generates the correct configuration files for your chosen platform - no environment variables needed!
|
|
|
|
## Documentation
|
|
|
|
For detailed guides, see the included blog posts:
|
|
- **[Getting Started](src/content/posts/getting-started.md)** - complete setup and workflow guide
|
|
- **[Formatting Reference](src/content/posts/formatting-reference.md)** - comprehensive formatting reference
|
|
- **[Vault CMS Guide](src/content/posts/vault-cms-guide.md)** - Obsidian vault walkthrough
|
|
- **[Obsidian Embeds Demo](src/content/posts/obsidian-embeds-demo.md)** - Obsidian embed examples
|
|
|
|
**For AI Agents & Developers:** See [AGENTS.md](AGENTS.md) for comprehensive technical documentation.
|
|
|
|
## Star History
|
|
|
|
[](https://www.star-history.com/#davidvkimball/astro-modular&type=date&legend=top-left)
|
|
|
|
## Acknowledgments
|
|
|
|
[Spaceship Astro theme](https://github.com/aitorllj93/astro-theme-spaceship) for the graph view functionality upon which this theme's is based.
|
|
|
|
[ogImage.click](https://ogimage.click/) to generate the open graph image used for this theme.
|
|
|
|
## Contributing
|
|
|
|
This is an open-source project. Feel free to submit feature requests, report bugs, or contribute improvements.
|
|
|
|
If you are contributing code back to the theme itself, please fork the repository and submit a Pull Request. **Do not fork the repository if you are just building your own site from this template.**
|
|
|
|
## License
|
|
|
|
[MIT License](https://github.com/davidvkimball/astro-modular?tab=MIT-1-ov-file)
|