Skip to content

Commit 51c14d9

Browse files
LeadcodeDevLeadcodeDev
committed
feat: write explainer news blog
1 parent c20a6be commit 51c14d9

6 files changed

Lines changed: 137 additions & 86 deletions

File tree

‎apps/blog/astro.config.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,18 @@ import { defineConfig } from 'astro/config'
22
import react from '@astrojs/react'
33
import mdx from '@astrojs/mdx'
44
import tailwindcss from '@tailwindcss/vite'
5+
import remarkDirective from 'remark-directive'
56
import { shikiConfig } from '@explainer/mdx/shiki'
67
import { remarkAutoImport } from '@explainer/mdx/remark-auto-import'
8+
import { remarkDirectiveHandler } from '@explainer/mdx/remark-directive-handler'
79
import { thumbnailIntegration } from '@explainer/thumbnail/integration'
810

911
export default defineConfig({
1012
site: 'https://blog.example.com',
1113
integrations: [
1214
react(),
1315
mdx({
14-
remarkPlugins: [remarkAutoImport],
16+
remarkPlugins: [remarkAutoImport, remarkDirective, remarkDirectiveHandler],
1517
}),
1618
thumbnailIntegration({
1719
appName: 'Blog',

‎apps/blog/package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,8 @@
2020
"@explainer/ui": "workspace:*",
2121
"@explainer/mdx": "workspace:*",
2222
"@explainer/thumbnail": "workspace:*",
23-
"@iconify/react": "^5.2.0"
23+
"@iconify/react": "^5.2.0",
24+
"remark-directive": "^4.0.0"
2425
},
2526
"devDependencies": {
2627
"@types/react": "^19.0.0",

‎apps/blog/src/content/posts/introducing-explainer-v2.mdx‎

Lines changed: 121 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,148 @@
11
---
22
title: Introducing Explainer v2
3-
description: A new documentation boilerplate with multi-project support, versioning, and i18n.
3+
description: Explainer v2 is a monorepo documentation boilerplate built with Astro, React, and Tailwind CSS 4 — giving you docs, blog, and website apps ready to go with multi-project support, versioning, i18n, and more.
44
date: 2026-03-10
5-
tags: [announcement, release]
5+
tags: [announcement, release, documentation, open-source]
66
author: leadcode_dev
77
---
88

99
# Introducing Explainer v2
1010

11-
We're excited to announce **Explainer v2**, a complete rewrite of our documentation boilerplate.
11+
We're excited to announce **Explainer v2** — a complete rewrite of our documentation boilerplate, now built as a **monorepo** powered by [Astro](https://astro.build), React, Tailwind CSS 4, and pnpm. It ships three independent apps — **docs**, **blog**, and **website** — that share common packages for MDX rendering, UI components, and configuration.
1212

13-
## What's New
13+
Whether you're documenting a single library or an entire ecosystem of projects, Explainer v2 gives you everything you need out of the box.
1414

15-
<Callout variant="info" title="Key Features">
16-
Multi-project docs, versioning, i18n, and independent deployments.
17-
</Callout>
15+
## Why Explainer?
1816

19-
### Multi-Project Support
17+
:::callout{variant="info" title="The problem"}
18+
Documentation tooling is fragmented. You need one tool for docs, another for your blog, another for your landing page — each with its own configuration, build pipeline, and deployment story. Keeping them consistent is a maintenance burden.
19+
:::
2020

21-
You can now host documentation for multiple projects in a single instance, each accessible via a dropdown switcher.
21+
Explainer solves this by giving you a **single, ready-to-use monorepo** where docs, blog, and website live side by side. Shared packages ensure consistent styling and MDX components across all three apps, while each app remains independently deployable.
2222

23-
### Versioning
23+
## Key Features
2424

25-
Each project can have multiple versions. Use the `default` version for unversioned docs, or add named versions like `v1`, `v2`.
25+
Explainer v2 comes packed with features designed for real-world documentation needs:
2626

27-
### Internationalization
27+
::::card-group{cols=2}
28+
:::card{label="Multi-Project Docs" icon="lucide:layers" href="/en/explainer/features/multi-project"}
29+
Host documentation for multiple projects in a single instance. Each project gets its own sidebar, versioning, and navigation — accessible via a dropdown switcher.
30+
:::
2831

29-
Full i18n support with URL prefix routing (`/fr/...`, `/en/...`) and automatic browser language detection.
32+
:::card{label="Versioning" icon="lucide:git-branch" href="/en/explainer/features/versioning"}
33+
Ship docs for multiple versions of your project. Use `default` for unversioned docs, or add named versions like `v1`, `v2` — readers switch between them seamlessly.
34+
:::
35+
36+
:::card{label="Internationalization" icon="lucide:globe" href="/en/explainer/features/internationalization"}
37+
Full i18n support with URL prefix routing (`/fr/...`, `/en/...`), automatic browser language detection, and per-locale navigation.
38+
:::
39+
40+
:::card{label="Full-Text Search" icon="lucide:search" href="/en/explainer/features/search"}
41+
Built-in search powered by Pagefind. Your docs are indexed at build time — no external service required, fully static and blazing fast.
42+
:::
43+
44+
:::card{label="OG Thumbnails" icon="lucide:image" href="/en/explainer/features/thumbnails"}
45+
Automatically generate Open Graph images for every documentation page, giving your content rich previews when shared on social media.
46+
:::
47+
::::
48+
49+
## Rich MDX Components
50+
51+
Explainer v2 ships with a library of custom MDX components that are **auto-imported** into every content file — no import statements needed. Here's a taste:
52+
53+
:::callout{variant="success"}
54+
This callout was written with a single directive — no imports, no boilerplate. Explainer's MDX pipeline handles everything for you.
55+
:::
56+
57+
::::card-group{cols=3}
58+
:::card{label="Callouts" icon="lucide:message-circle" href="/en/explainer/mdx-components/callout"}
59+
Info, success, warning, danger, and note variants for highlighting important content.
60+
:::
61+
62+
:::card{label="Cards & Card Groups" icon="lucide:layout-grid" href="/en/explainer/mdx-components/card"}
63+
Visual cards with icons and links, arranged in responsive grid layouts.
64+
:::
65+
66+
:::card{label="Code Blocks" icon="lucide:code" href="/en/explainer/code-blocks/syntax-highlighting"}
67+
Syntax highlighting, line numbers, line highlighting, code groups with tabs, and more.
68+
:::
69+
::::
70+
71+
You also get **Tabs**, **Steps**, **Code Groups**, and **Preview** components — all documented in the [components reference](/en/explainer/mdx-components/callout).
72+
73+
## Three Apps, One Monorepo
74+
75+
| App | Purpose | Port | Package |
76+
|-----|---------|------|---------|
77+
| **Docs** | Technical documentation with sidebar navigation, versioning, and search | `4321` | `@explainer/docs` |
78+
| **Blog** | Content-driven blog with tags, authors, and RSS | `4322` | `@explainer/blog` |
79+
| **Website** | Marketing landing page | `4323` | `@explainer/website` |
80+
81+
All three apps share common packages for MDX processing, UI components, and Tailwind configuration. Learn more about the [project structure](/en/explainer/project-structure).
3082

3183
## Getting Started
3284

85+
::::step-group
86+
:::step{title="Clone the repository"}
3387
```bash
34-
git clone https://github.com/you/explainer-v2
88+
git clone https://github.com/explainer/explainer-v2
3589
cd explainer-v2
90+
```
91+
:::
92+
93+
:::step{title="Install dependencies"}
94+
Explainer uses pnpm workspaces. Install everything with a single command:
95+
96+
```bash
3697
pnpm install
98+
```
99+
:::
100+
101+
:::step{title="Start developing"}
102+
Launch all three apps in development mode:
103+
104+
```bash
37105
pnpm dev
38106
```
39107

108+
Or start a single app:
109+
110+
```bash
111+
pnpm dev --filter @explainer/docs
112+
```
113+
:::
114+
::::
115+
116+
For the full setup guide, including prerequisites and configuration, head to the [Getting Started](/en/explainer/getting-started) page.
117+
118+
## Deploy Anywhere
119+
120+
Explainer v2 apps are standard Astro projects — deploy them wherever you like:
121+
122+
::::card-group{cols=2}
123+
:::card{label="Docker" icon="lucide:container" href="/en/explainer/deployment/docker"}
124+
Containerize each app independently with the included Dockerfiles and docker-compose setup.
125+
:::
126+
127+
:::card{label="Vercel" icon="lucide:triangle" href="/en/explainer/deployment/vercel"}
128+
Zero-config deployment with automatic builds and preview environments.
129+
:::
130+
131+
:::card{label="Cloudflare Pages" icon="lucide:cloud" href="/en/explainer/deployment/cloudflare"}
132+
Deploy to Cloudflare's edge network for global performance.
133+
:::
134+
135+
:::card{label="GitHub Pages" icon="lucide:github" href="/en/explainer/deployment/github-pages"}
136+
Free hosting with GitHub Actions for automated builds on every push.
137+
:::
138+
::::
139+
40140
## What's Next
41141

42-
We're working on search integration and dark mode support. Stay tuned!
142+
Explainer v2 is ready for you to use today. We're actively working on expanding the feature set — but the foundation is solid and production-ready.
143+
144+
:::callout{variant="note" title="Explore the docs"}
145+
Head over to the [documentation](/en/explainer/getting-started) to get started, or browse the [feature pages](/en/explainer/features/multi-project) to see everything Explainer v2 has to offer.
146+
:::
147+
148+
If you find Explainer useful, give us a star on GitHub and share it with your team. We'd love to hear what you build with it!

‎apps/blog/src/content/posts/markdown-components.mdx‎

Lines changed: 0 additions & 67 deletions
This file was deleted.

‎apps/blog/src/pages/[slug].astro‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,9 @@
22
import { getCollection, render } from 'astro:content'
33
import PostLayout from '../layouts/post.astro'
44
import { getPublishedPosts, getPostSlug, getReadingTime } from '../lib/posts'
5-
import { mdxOverrides, Callout, Tabs, Tab, Steps, Step, CodeGroup } from '@explainer/mdx'
5+
import Pre from '@explainer/mdx/overrides/pre.astro'
6+
import Blockquote from '@explainer/mdx/overrides/blockquote.astro'
7+
import { Code, H1, H2, H3, H4, H5, H6, Link, Paragraph, UnorderedList, OrderedList } from '@explainer/mdx'
68
79
export async function getStaticPaths() {
810
const allPosts = await getCollection('posts')
@@ -31,5 +33,9 @@ const articleUrl = new URL(`/${getPostSlug(post)}`, Astro.site ?? Astro.url.orig
3133
headings={headings}
3234
url={articleUrl}
3335
>
34-
<Content components={{ ...mdxOverrides, Callout, Tabs, Tab, Steps, Step, CodeGroup }} />
36+
<Content components={{
37+
h1: H1, h2: H2, h3: H3, h4: H4, h5: H5, h6: H6,
38+
a: Link, p: Paragraph, ul: UnorderedList, ol: OrderedList,
39+
pre: Pre, code: Code, blockquote: Blockquote,
40+
}} />
3541
</PostLayout>

‎pnpm-lock.yaml‎

Lines changed: 3 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)