MDXBlog is a free starter template project that is easy to install and deploy. Using MDX (Markdown + JSX) and Next.js, it generates static pages that are fast, secure, and SEO-friendly. The app is designed to be easy to use and customize, with a clean, modern design that is fully responsive and mobile-friendly.

Our mission is to take the friction out of content creation. We wanted a blogging platform that was easy to use, developer friendly - and that makes content creation a pleasure, so we built one with Next.js and MDX. MDXBlog (mdxblog.io) is an independently created app. We have no affiliation with the MDX team or Next.js, we are simply fans of the technology and wanted to create a simple, free, easy-to-use blog template for ourselves and to share with any other interested developers.

Why MDXBlog?

MDXBlog stores posts as markdown files on the local machine, eliminating the need for a round trip to a database every time we want to write or edit a post. Content creation with local files just feels more intuitive. We can even create content in our favorite text editor or IDE.

MDXBlog uses MDX format which gives us the power to include React components directly in the Markdown documents. This means we can include interactive elements like forms, buttons, and more in our posts, in a much more developer-friendly way.

Key Features:

• Style as You Write: MDX content is styled with Markdown syntax. This is the most developer-frindly way: styling without needing to lift your fingers from the keyboard.

• Quick Post Creation: In development mode, creating a new post is as simple as clicking a '+' icon in the nav bar. It instantly generates a new post for you to start writing.

• Scheduled Publishing: Set future dates for your posts, and MDXBlog will ensure they go live when they’re supposed to—no manual intervention required.

• Custom Components: Seamlessly add YouTube videos, images, and code snippets to your posts using built-in React components.

• Dynamic Rendering: Next.js handles the rendering of your content, ensuring it loads quickly and is SEO friendly. You can focus on writing, and MDXBlog takes care of the rest.

• Utilizing metadata objects in each post, we extract crucial metadata for SEO and rendering purposes.

• Only relevant posts are displayed, based on their publication date.

• In development mode, additional tools like EditPostButton and OpenInVSCode are available, enhancing the ease of content management and editing.

To get started, clone the repo, run npm install, and you should be good to go.

Table of Contents

• Getting Started

  • Installation
  • How to Use MDXBlog
  • Detailed Instructions

• Markdown and MDX Guide

  • Markdown Syntax
  • MDX Syntax

• Custom MDX Components

  • <YouTube />
  • <Image />
  • code

• Notes

  • Scheduled Publishing

Getting Started

• Clone the repo
• Run 'npm install'
• Run 'npm run dev'
• Create a .env.local file. See the .env.example file at the root of the project for the required environment variables.
• Open 'http://localhost:3000' in your browser
• Create a remote repo on GitHub
• Push your local repo to GitHub
• Deploy on Vercel

Check out an article on the blog for a more detailed guide on how to install MDXBlog and deploy on Vercel.

How to Use MDXBlog:

Instructions:

Create a post

• Use the '+' icon in the nav bar, in development mode only, to create a new post - or simply create a new MDX file in the 'data/posts' directory, manually.
• Edit posts in the browser or manually using VS Code (recommended), or any other text editor.

You'll find a directory called content/blogs where you can create your blog posts. Follow the template and you will be fine.

Markdown and MDX Guide

Markdown Syntax

• Headings: Use # for headings. More # symbols mean smaller headings.

  markdownCopy
  # H1 Heading
  
  ## H2 Heading
  
  ### H3 Heading
  

• Paragraphs: Simply write text to create a paragraph.

  markdownCopy
  This is a paragraph of text.
  

• Bold and Italic Text: Use ** or __ for bold and * or _ for italic.

  markdownCopy
  This is **bold** text and this is _italic_ text.
  

• Lists:

  • Unordered List: Use -, *, or + for bullet points.

    markdownCopy
    - Item 1
    - Item 2
    

  • Ordered List: Use numbers followed by a period.

    markdownCopy
    1. First item
    2. Second item
    

• Links: Use [text](url) for hyperlinks.

  markdownCopy
  [OpenAI](https://openai.com)
  

• Images: Use ![alt text](image url) to embed images.

  markdownCopy
  ![A cat](https://example.com/cat.jpg)
  

• Code Blocks: Use triple backticks for code blocks.

  markdownCopy
  

  javascriptCopy
  console.log("Hello, world!");
  

MDX Syntax

• Embedding Components: Directly embed React components or custom components within your content.

  jsxCopy
  import MyButton from "./MyButton";
  
  <MyButton>Click Me!</MyButton>;
  

• Combining Markdown and Components: Use markdown for content structure and components for interactivity.

  jsxCopy
  ## A Section with a Button
  
  Here’s a paragraph of text before the button.
  
  <MyButton>Click Me!</MyButton>
  
  Here’s another paragraph after the button.
  

Custom MDX Components

MDXBlog provides custom components to enhance your content with interactive elements and visual appeal. These components are imported in the configuration, so they can be used in MDXBlog without an explicit import statement in the MDX document. Here are some of the custom components available:

<YouTube />: Seamlessly embed YouTube videos within your content

To embed a YouTube video, use the <YouTube /> component. Provide the id of the YouTube video you want to embed:

<YouTube id="aqz-KE-bpKQ" />

• id: The unique identifier for the YouTube video. This can be found in the video URL after v=. For example, in https://www.youtube.com/watch?v=aqz-KE-bpKQ, the id is aqz-KE-bpKQ.

The YouTube component is a custom MDX component that allows you to embed YouTube videos directly into your content. Simply provide the video ID, and the component will handle the rest.

<Image />: Integrate images elegantly, enhancing the visual appeal of your posts

To add an image to your content, use the <Image /> component. You can also add a caption to describe the image:

<Image src="/images/posts/how-to-use-images/grass-tree-sky.jpg" caption="trees, grass, and sky" />

• src: The path to your image file. This should be relative to the root of your project or the public folder if using Next.js.
• caption (optional): A short description or caption for the image.

trees, grass, and sky

Code: Include and showcase code snippets with clarity and style

Inline Code

Inline code can be added using single backticks (`):

`const message = "Hello, World!";`

Like this:

const message = "Hello, World!";

Code Blocks

To display a block of code, use the standard Markdown syntax with triple backticks (```) followed by the language identifier:

```javascript
console.log("Hello World")
```

• language identifier (optional): Specify the programming language for syntax highlighting. In the example above, javascript is used. Replace it with the appropriate language if different.

Here is a simple example of a function that doubles the numbers in an array:

javascriptCopy
function doubleNumbers(numbers) {
  return numbers.map((number) => number * 2);
}

// Example usage
const numbers = [1, 2, 3, 4, 5];
const doubled = doubleNumbers(numbers);

console.log(doubled); // Output: [2, 4, 6, 8, 10]

Code blocks allow copy-pasting and easy readability, making it simple for readers to understand and use the code snippets you provide.

Notes

Scheduled Publishing

MDXBlog allows you to schedule posts for future publication. This feature is particularly useful when you want to prepare content in advance and have it automatically published at a specific date and time.

When you create or edit a post you will see a 'Date' field. You can set the date and time for when you want the post to go live. Once you save the post, MDXBlog will automatically publish it at the scheduled date.

Note that there is also a "date modified" property. Each time you edit the post, the date modified will be updated. This is useful for tracking changes to your content. Date modified will be displayed at the top of post, next to the category indicator - unless the published date is later than the modified date - wherin it will display the publishe date. If you want the published date to match the modified date, you can manually set the published date to the same as the modified date. Remember to note that future dated posts will always be unlisted (not visible on your blog roll) until the scheduled publishe date. This is true even if you change the created date to a later date than the current time subsequent to a previous publication.

More About MDXBlog

MDXBlog represents a blend of technological innovation and user-centric design, providing a platform that's not only a pleasure to use but also powerful in its capabilities. Whether you're a developer, a content creator, or someone passionate about blogging, MDXBlog offers you the tools to share your stories and ideas with the world effortlessly.

Find relevant articles on the blog:

• Installation Guide
• A User Guide