DOCSEARCHbyAlgolia
Submit Docs

Astro Modular

repository·master·Indexed 42 days ago

https://github.com/davidvkimball/astro-modular

A flexible Astro-based blog theme version 1.1.1 optimized for Obsidian users to use as a CMS via Vault CMS. It includes a scaffolding CLI tool, create-astro-modular, and supports custom theme creation, multiple deployment platforms (Netlify, Vercel, GitHub Pages, Cloudflare Workers), and deep configuration for typography, profile pictures, and home page layouts.

Tokens
25.5K
Snippets
91
Records
126
Agent score
53%

What's inside Astro Modular

  1. What is Astro Modular?

    master
    Astro Modular is an Astro blog theme template specifically designed for Obsidian users. It functions as a bridge that turns an Obsidian vault into a powerful CMS for instant blog publishing. The theme is built to support rich markdown features common in Obsidian, such as Wikilinks and callouts, ensuring a seamless transition between your local vault and your published website.

  2. Understand the Content Structure

    master

    Astro Modular organizes content within the src/content/ directory. This structure supports folder-based organization and co-located assets.

    Directory Layout:

    • posts/: Blog posts.
    • pages/: Static pages.
    • special/: Special pages like home or 404.
    • projects/: Featured projects.
    • docs/: Documentation content.
    • .obsidian/: Obsidian vault configuration files.

  3. How the modular design works in Astro Modular

    master
    Astro Modular follows a modular design philosophy where features are not hard-coded but can be toggled. You can enable or disable specific theme features through a single configuration file. This allows you to keep your site fast and focused by only including the functionality required for your specific use case.

  5. Manage content with Home Base and Bases CMS

    master

    These two plugins work in tandem to provide a CMS-like experience within Obsidian:

    • Home Base: Pins a home icon to your tab bar that returns you to a .base file. This file acts as a directory of all content, listed in reverse-chronological order.
    • Bases CMS: Treats content grids like a CMS. You can perform bulk edits, rename content directly from the view, or toggle draft status.

    Configuring Views in Bases CMS:

    1. Select the current view in the top left to reveal the list.
    2. Click the right chevron arrow to open "configure view" options.
    3. Configure desired properties.
    4. Set the default location for new notes at the bottom of the configuration menu (defaults to the current base folder).

  6. Use the `base` directive to embed data views

    master

    You can embed complex data views (collections of posts/pages) using the base directive syntax. This allows you to define filters, formulas, properties, and view types (like tables or cards) directly in your markdown.

    Ways to embed a .base file:

    1. Markdown embed: ![](path/to/file.base)
    2. Wikilink embed: ![[path/to/file.base]]

    Key Configuration Options within base:

    • filters: Define which files to include (e.g., by folder or extension).
    • formulas: Create custom properties using logic (e.g., generating slugs).
    • properties: Map file metadata to display names.
    • views:
      • type: Set to table or cards.
      • name: The title of the view.
      • limit: (Optional) Restrict the number of items shown.
      • sort: Define the sorting order and direction.
      • image: Specify which property to use for card images.
    views:
  - type: table
    name: Posts
    limit: 2

    // Or as a wikilink ![[Home.base]]

    // Or as a markdown embed

  7. Vault CMS core features and plugins

    master

    Vault CMS includes several community plugins to automate the workflow between Obsidian and Astro:

    Content & Organization

    • Astro Composer: Automates post creation and manages slugs using kebab-case.
    • Bases CMS: Provides a CMS-like homepage using Obsidian Bases for content management.
    • Property Over Filename: Uses the title property as the primary identifier instead of the filename.
    • Tag Wrangler: Enables bulk tag management.

    Media Management

    • Image Inserter: Pull images from Unsplash or other sources using CTRL + '.
    • Paste Image Rename: Automatically renames pasted images to kebab-case for SEO.
    • Paste Image Into Property: Inserts images directly into frontmatter properties.

    Writing & Workflow

    • Zen Mode: Full-screen writing mode triggered by CTRL + SHIFT + Z.
    • Git Integration: Optional instant-publishing via the Git plugin using CTRL + SHIFT + S.
    • SEO: Includes a content audit tool for search engine optimization.
    • Simple Banner: Automatically displays banners for posts containing cover images.

  8. Use Property Over File Name for cleaner UI

    master

    The Property Over File Name plugin allows you to use the title property as the primary label for notes instead of their kebab-case filenames.

    • Linking: When linking, the title property is automatically used as the hyperlinked text.
    • Searching/Display: Notes will be identified by their title in searches and tab displays.
    • Configuration: Behavior can be adjusted within the plugin settings.

  9. Color scale guidelines for themes

    master

    When defining colors for your custom theme, follow these usage guidelines for the color scales:

    Primary Colors

    • 50-100: Light backgrounds, subtle elements
    • 200-300: Borders, dividers, muted text
    • 400-500: Medium emphasis text, default colors
    • 600-700: High emphasis text, interactive elements
    • 800-900: Dark backgrounds, headers
    • 950: Darkest backgrounds, high contrast text

    Highlight Colors

    • 400-500: Links, interactive elements (light mode)
    • 600-700: Links, interactive elements (dark mode)
    • Usage: Use sparingly for accents, links, and call-to-action elements.

  10. Set up and run Astro Modular

    master

    After obtaining the code, follow these steps to initialize your local development environment:

    1. Install pnpm (if not already installed):
      npm install -g pnpm
    2. **Install dependencies**:
   ```bash
pnpm install
    1. Start the development server:
      pnpm dev
       The blog will be available at `http://localhost:5000`.
4. **Build for production**:
   ```bash
pnpm build
    pnpm install
pnpm dev
pnpm build

  11. Use Oxygen Theme and UI Focus modes

    master

    The Oxygen theme and associated plugins provide several ways to focus on writing and customize the interface:

    UI Toggling (Hotkeys)

    • Left Side Panel: CTRL + ALT + Z
    • Right Side Panel: CTRL + ALT + X
    • Tab Bar: CTRL + ALT + S
    • Zen Mode: CTRL + SHIFT + Z (hides all elements except content).

    Focus Tools

    • Explorer Focus: Simplifies the file explorer to show only the directory relevant to your currently open file. Use the toggle focus button or right-click a directory.
    • UI Tweaker: Allows you to hide and adjust various UI elements.
    • Style Settings: If installed, provides even deeper control over the Oxygen theme colors and appearance.
    Toggle Left Panel: CTRL + ALT + Z
Toggle Right Panel: CTRL + ALT + X
Toggle Tab Bar: CTRL + ALT + S
Enter/Exit Zen Mode: CTRL + SHIFT + Z

  12. Reference images in folder-based posts

    master

    In a folder-based post, you can reference images stored in the same directory as your index.md using standard Markdown syntax or Wikilink syntax. You can also reference images in an attachments/ subfolder.

    Supported methods:

    • Standard Markdown: ![Alt text](filename.png)
    • Wikilink syntax: ![[filename.png]]
    • Subfolder paths: ![Alt text](attachments/filename.jpg)
    ![Forest.](forest.png)

![[forest.png]]

![Lush forest](attachments/lush-forest.jpg)