Gremoire

🖼️ Building a Visual Content Publishing Site with VitePress & Astro ​

“Not all knowledge is text — sometimes, it’s drawn, illustrated, and meant to be seen.”
— Mark Wayne Menorca, Gremoire Collections

Overview ​

Developers often rely on VitePress for text-based documentation or personal notes.
But what if your content isn’t just text — what if you want to publish images, visual tutorials, or even manhua-style stories in a lightweight, self-hosted site?

This guide walks you through creating a visual content publishing system using VitePress (for writing) and Astro (for image-based content).

Why Astro over VitePress for Visual Posts ​

While VitePress is perfect for text-heavy markdown and technical docs, it has a few limits for visual-first content:

  • No built-in image gallery or lazy-loading layout.
  • Limited control for multi-image posts.
  • No “chapter” or navigation system for comic-like reading.

That’s where Astro shines.

Astro combines the power of markdown + web components to build image-rich layouts while staying fast and deployable to Vercel, Netlify, or GitHub Pages.

Setup — The Hybrid Publishing Stack ​

PurposeToolNotes
Text-based writing (guides, docs)VitePressYour current docs/ site
Image-based articles / comicsAstroPlaced in /gallery or /manhua folder
HostingVercelSupports both static sites easily
Version ControlGitHubSyncs both VitePress and Astro builds

Step 1 — Create the Astro Project ​

In your repository root, run:

bash
npm create astro@latest gallery
cd gallery
npm install
npm run dev

Astro will create a starter site in /gallery.

Step 2 — Add MDX and Image Support ​

bash
npm install @astrojs/mdx @astrojs/image

Edit your astro.config.mjs:

js
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import image from '@astrojs/image';

export default defineConfig({
  integrations: [mdx(), image()],
  site: 'https://yourdomain.vercel.app',
});

This allows you to write Markdown + React-style components and use optimized <Image /> elements.

📸 Step 3 — Structure Chapters or Visual Articles ​

You can organize your visuals like this:

/gallery
 ├─ public/
 │   └─ chapters/
 │       ├─ 1/
 │       │   ├─ page1.jpg
 │       │   └─ page2.jpg
 │       └─ 2/
 │           ├─ page1.jpg
 │           └─ page2.jpg
 ├─ src/
 │   ├─ layouts/
 │   │   └─ ChapterLayout.astro
 │   └─ pages/
 │       ├─ index.astro
 │       └─ chapter-1.mdx

Then in chapter-1.mdx:

mdx
---
title: "Chapter 1 – Awakening"
layout: ../layouts/ChapterLayout.astro
---

<Image src="/chapters/1/page1.jpg" alt="Page 1" />
<Image src="/chapters/1/page2.jpg" alt="Page 2" />

Step 4 — Build the Chapter Layout ​

src/layouts/ChapterLayout.astro:

astro
---
const { title } = Astro.props;
---

<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>{title}</title>
    <style>
      body {
        background: #121212;
        color: #f8f8f2;
        font-family: 'Inter', sans-serif;
        margin: 0;
        padding: 0;
      }
      main {
        display: flex;
        flex-direction: column;
        align-items: center;
      }
      img {
        width: 100%;
        max-width: 900px;
        border-radius: 8px;
        margin: 0.5rem 0;
        box-shadow: 0 4px 12px rgba(0,0,0,0.3);
      }
    </style>
  </head>
  <body>
    <main>
      <slot />
    </main>
  </body>
</html>

Step 5 — Deploy on Vercel ​

Add the Astro project to your Vercel Dashboard, set the root directory to /gallery,
and the build command to:

bash
npm run build

Then preview at gallery.yourdomain.com.

Optional: Integrate VitePress + Astro Together ​

You can host both at once by merging their static builds:

vitepress build docs
astro build gallery
cp -r gallery/dist/* dist/

Then deploy /dist to your host.

Summary ​

FeatureTool
Markdown articlesVitePress
Image/comic postsAstro
DeploymentVercel
DesignYour theme (Monokai / Dark)

“A Gremoire doesn’t store spells — it stores understanding.
A developer’s Gremoire does the same, but in code, images, and words.”