Skip to main content

Blog Functionality

Docusaurus includes a built-in blog plugin that provides a full-featured blogging platform with support for authors, tags, RSS feeds, and rich content formatting.

Overview​

The blog is configured in docusaurus.config.ts and uses the @docusaurus/preset-classic blog preset. Blog posts are stored in the docusaurus/blog/ directory as MDX files.

Features​

  • MDX support: Write blog posts with JSX components embedded in Markdown
  • Author management: Define authors in blog/authors.yml with names, titles, URLs, and profile images
  • Tag system: Organize posts with tags defined in blog/tags.yml with labels, permalinks, and descriptions
  • RSS/Atom feeds: Automatic feed generation for blog subscribers
  • Reading time: Automatic calculation and display of estimated reading time
  • Truncation: Use <!-- truncate --> to control post preview length
  • SEO optimization: Built-in meta tags, OpenGraph, and Twitter card support
  • Responsive images: Automatic image optimization and responsive sizing

Configuration​

The blog is configured in docusaurus.config.ts with enhanced settings for better SEO and user experience. See Blog Plugin Configuration for complete documentation of all available options.

Key settings:

  • SEO: Custom title, description, and copyright for feeds
  • Sidebar: Show 10 recent posts
  • Reading time: Enabled for all posts
  • Feeds: RSS and Atom feeds with XSLT styling
  • Best practices: Warnings for inline tags/authors and missing truncate markers

Key options:

  • showReadingTime: Display estimated reading time on posts
  • feedOptions: Enable RSS and Atom feed generation
  • editUrl: GitHub edit links for blog posts
  • onInlineTags/onInlineAuthors: Warn when authors/tags are defined inline instead of in YAML files
  • onUntruncatedBlogPosts: Warn when posts don't include <!-- truncate -->

File Structure​

docusaurus/blog/
├── authors.yml              # Author definitions
├── tags.yml                 # Tag definitions
├── YYYY-MM-DD-post-slug.mdx # Blog posts (MDX format)
└── assets/                  # Blog images and assets (optional)

Creating a Blog Post​

Basic Post Structure​

Create a new file in docusaurus/blog/ with the naming pattern YYYY-MM-DD-slug.mdx:

---
slug: "why-move-your-website-from-wordpress-to-webflow"
title: "Why Move Your Website From Wordpress To Webflow?"
date: "2025-09-29"
tags:
  - website-ux
description: "Migrations might be a pain, but longer term they're worth it."
image: "/img/blog/featured-image.avif"
authors:
  - pacing-agency
---

Your introductory paragraph here...

<!-- truncate -->

Main content starts here after the fold...

Frontmatter Fields​

FieldRequiredDescription
slugNoURL slug (defaults to filename without date)
titleYesPost title
dateYesPublication date (YYYY-MM-DD format)
tagsNoArray of tag IDs from tags.yml
descriptionNoPost summary for SEO and previews
imageNoFeatured image URL (absolute or relative)
authorsNoArray of author IDs from authors.yml

Truncation Marker​

Use <!-- truncate --> to control where the post preview ends on the blog index:

This text appears in the preview...

<!-- truncate -->

This text only appears on the full post page.

Authors Configuration​

Define authors in blog/authors.yml:

ben-power:
  name: Ben Power
  title: Founder, Pacing Agency
  url: https://pacing.agency
  image_url: https://pacing.agency/img/ben-power.jpg

pacing-agency:
  name: Pacing Agency
  title: Digital Marketing Agency
  url: https://pacing.agency
  image_url: https://pacing.agency/img/logo.svg

Then reference authors in post frontmatter:

authors:
  - ben-power
  - cam-bowen

Tags Configuration​

Define tags in blog/tags.yml:

website-ux:
  label: Website & UX
  permalink: /website-ux
  description: Website design, development, and user experience topics

data-analytics:
  label: Data & Analytics
  permalink: /data-analytics
  description: Technical insights on tracking, analytics, and data accuracy

Then reference tags in post frontmatter:

tags:
  - website-ux
  - data-analytics

Using MDX Components​

Import and use React components in blog posts:

---
title: My Post
---

import FAQStructuredData from '@site/src/theme/MDXComponents/FAQStructuredData';

## My heading

Regular markdown content...

<FAQStructuredData 
  faqs={[
    { question: "What is this?", answer: "An answer" }
  ]} 
  collapsible={true} 
/>

Blog URLs​

  • Blog index: /blog
  • Post page: /blog/slug-from-frontmatter
  • Tag pages: /blog/tags/tag-permalink
  • Author pages: /blog/authors/author-id (if multiple posts)
  • RSS feed: /blog/rss.xml
  • Atom feed: /blog/atom.xml

SEO Best Practices​

  1. Always include description: Used for meta descriptions and OpenGraph
  2. Add featured images: Use image field for social sharing cards
  3. Use meaningful slugs: Keep slugs short, descriptive, and keyword-rich
  4. Include alt text: Add alt text to all images in post content
  5. Structure with headings: Use H2-H4 for proper document outline
  6. Add internal links: Link to related docs and other blog posts

Webflow Blog Sync​

For syncing blog posts from Webflow CMS to Docusaurus, see the sync script documentation:

# Run the Webflow blog sync script
python3 scripts/resources/webflow/scripts/sync_blog.py

See scripts/resources/webflow/README.md for complete sync script documentation.

The blog is integrated into navigation via:

  1. Navbar: Add blog link in docusaurus.config.ts navbar items
  2. Homepage: Link to /blog from homepage sections
  3. Sidebar: Blog is NOT in the docs sidebar (standalone section)

Example navbar configuration:

navbar: {
  items: [
    {
      type: 'docSidebar',
      sidebarId: 'tutorialSidebar',
      position: 'left',
      label: 'Docs',
    },
    {
      to: '/blog',
      label: 'Blog',
      position: 'left'
    },
    // ...
  ],
}

Local Development​

Start the dev server to preview blog posts:

cd docusaurus
npm start

Navigate to http://localhost:3000/blog to view the blog.

Build and Deploy​

Blog posts are automatically built and deployed with the main site:

cd docusaurus
npm run build

The blog is generated to build/blog/ with all posts, tag pages, and feeds.

Best Practices​

  1. Use descriptive filenames: 2025-01-15-server-side-tracking-guide.mdx is better than 2025-01-15-post.mdx
  2. Always include truncation marker: Keeps blog index clean and fast
  3. Optimize images: Use WebP or AVIF formats, compress before upload
  4. Leverage tags: Helps readers discover related content
  5. Update authors.yml: Add new team members as they start blogging
  6. Cross-link content: Link to relevant docs, tools, and other posts
  7. Test locally: Always preview posts before committing
  8. Use MDX sparingly: Only embed components when they add real value

Troubleshooting​

Post not showing up​

  • Check filename format: YYYY-MM-DD-slug.mdx
  • Verify frontmatter YAML is valid
  • Ensure date is not in the future
  • Check for build errors: npm run build

Author/tag not rendering​

  • Verify ID matches entry in authors.yml or tags.yml
  • Check YAML indentation (use spaces, not tabs)
  • Ensure YAML is valid (use a validator if needed)

Images not loading​

  • Use absolute paths /img/blog/image.jpg or relative paths
  • Place images in docusaurus/static/img/blog/
  • Check image file exists and path is correct
  • Verify image format is supported (jpg, png, webp, avif, svg)

MDX syntax errors​

  • Escape special characters in content: \{, \<, \>
  • Use code blocks for code examples (prevents JSX parsing)
  • Test with npm start or npm run build