raphaelmansuy/agentic_platform_reference
Overview
This skill helps developers build fast, SEO-optimized static sites with Docusaurus v3.9.2 using Markdown/MDX, metadata, and production-ready plugins. I focus on practical setup, content pipelines, image and performance optimizations, and smooth GitHub Pages deployment. The goal is to get searchable, shareable documentation and blogs live quickly with minimal ops overhead.
How this skill works
I scaffold a Docusaurus site and configure docusaurus.config.ts to centralize SEO metadata, plugins, and build options. Content authored as Markdown/MDX with frontmatter (title, description, image, keywords) generates semantic <head> tags and OpenGraph/Twitter cards. I add plugins like sitemap, ideal-image, gtag, and pwa, validate meta tags in a prod preview, and provide deployment steps and CI hints for GitHub Pages.
When to use it
- You need versioned API docs or technical docs with search and social previews
- Shipping an open-source project site or blog that must rank in search engines
- Deploying docs to GitHub Pages with custom domain and HTTPS
- Optimizing images and Lighthouse performance for static documentation
- You want MDX interactivity (React components) embedded in docs
Best practices
- Always include frontmatter: title, description, image, keywords per page to drive meta tags
- Set trailingSlash: true for GitHub Pages compatibility and consistent canonical URLs
- Enable @docusaurus/plugin-sitemap and a robots.txt to improve crawling and indexing
- Use @docusaurus/plugin-ideal-image or responsive WebP/AVIF to reduce payload and improve Lighthouse scores
- Test meta tags with Twitter Card Validator and Facebook Debugger; run Lighthouse and prod preview before deploy
Example use cases
- Scaffold a docs site for an open-source library with versioned API docs and blog
- Convert Markdown product docs to MDX to embed interactive examples and React components
- Improve SEO for an existing Docusaurus site by adding global metadata, sitemap, and optimized OG images
- Set up GitHub Actions to auto-deploy Docusaurus to GitHub Pages with a custom domain
- Run Lighthouse audits and configure ideal-image to push performance scores above 90
FAQ
Start with sitemap, ideal-image, and a Google gtag plugin. Add pwa if offline support is needed. Global metadata in config plus per-page frontmatter drives most SEO benefits.
How do I verify social preview images and meta tags?
Build and serve a prod preview (yarn build && yarn serve), inspect <head> in DevTools, and validate cards with Twitter Card Validator and Facebook Debugger.
