You do not need to move a code-based website into a hosted CMS just to publish useful articles. A small Markdown or MDX content folder, a blog route, and a few SEO essentials are enough for many sites.
The important part is not the choice between .md and .mdx. It is building a publishing path that consistently creates readable pages with stable URLs, correct metadata, and links search engines can discover.
This guide explains the pieces you need and the order in which to add them.
1. Check how the website is built and deployed
Before creating a content folder, identify the framework and hosting process.
Look in the repository for clues such as package.json, framework configuration files, and the command used to build the site. Confirm which branch triggers production deployment.
Also check whether a content system already exists. Search for .md and .mdx files, blog routes, documentation pages, or frontmatter parsers. Extending an existing pattern is usually safer than introducing a second one.
Make a note of:
- The framework and version
- The production branch
- The command that builds the site
- The folder containing public assets
- Any existing content directory
- The site's preferred domain, including whether it uses
www
Do not create article files until you know how the application will read them.
2. Choose a simple content structure
A clear folder is easier to maintain than a clever one. For example:
content/
blog/
how-to-choose-a-widget.mdx
Each file should contain the metadata your blog page needs. A practical starting point is:
---
title: "How to Choose a Widget"
description: "Learn what to compare before choosing a widget for a small team."
date: "2026-09-17"
slug: "how-to-choose-a-widget"
tags: ["Widgets", "Buying guide"]
searchIntent: "commercial"
author: "Your name"
draft: false
---
Use the filename or the slug consistently; do not let them silently produce two different URLs. Validate required fields during the build so a missing title or invalid date stops the deployment before it creates a broken page.
Set searchIntent to the job the page serves: informational for learning, commercial for comparing options, transactional for completing a task, or navigational for finding help with a specific product or destination. This field should guide the article's structure; it is not a label to repeat in the visible copy.
MDX is useful when an article needs approved components. Plain Markdown is simpler when articles contain only text, images, links, lists, and tables. Do not enable arbitrary executable content merely because MDX supports it.
3. Create the blog index and article route
Your blog needs two public views:
/bloglists published articles./blog/article-slugrenders one article.
The index should show a clear title, description, publication date, and link for each article. Exclude drafts from the production list.
The article route should convert Markdown safely, generate stable heading IDs where needed, and return a real not-found response for unknown slugs. Avoid loading every article into client-side JavaScript when the framework can render pages during the build or on the server.
Add links to the blog from your main navigation or footer. A sitemap can help discovery, but users and crawlers should also be able to reach the blog through ordinary links.
4. Generate metadata from the article file
Each public article should have its own understandable metadata:
- A page title that names the article's subject
- A description that explains what the reader will learn
- A canonical URL using the site's preferred domain
index, followfor public articles- Article Open Graph metadata for sharing
- An author name and profile URL
- Publication and meaningful modification dates
Use one URL format everywhere. If the canonical says https://example.com/blog/post, the sitemap and internal links should not switch to https://www.example.com/blog/post.
If an article has a share image, provide a real image with a stable public URL. Do not point to a local development address or a social-media page that may block image requests.
5. Add valid article structured data
BlogPosting structured data can describe the article to search engines. It should reflect the visible page rather than make extra claims.
Useful properties include:
headlinedescriptiondatePublisheddateModifiedmainEntityOfPageauthorpublisherimage, when the page has one
Structured data does not make an unhelpful article rank, and it does not guarantee a special search result. Treat it as accurate machine-readable documentation of the page.
6. Generate the sitemap and RSS feed from real articles
Do not maintain article URLs by hand in several files. Read the same content collection used by the blog pages and use it to generate:
- Sitemap entries for every published article
- The blog index entry
- Author pages, if they are public
- RSS items for published articles
Use the updated date as lastModified when an article has been meaningfully revised. Keep drafts, previews, editor pages, account pages, and application routes out of the public sitemap.
Your robots.txt can point to the sitemap and block crawling of private application areas. Remember that a robots rule is not access control. Authentication must protect private pages.
7. Connect Google Search Console
Once the production pages are live, verify the preferred site in Google Search Console. The exact verification method depends on whether you use a domain property or URL-prefix property and what access you have to DNS or the website.
Submit the sitemap URL, then inspect one real article URL. Confirm that Google can access the canonical page and that the page is not carrying an accidental noindex instruction.
Search Console will not show useful performance data immediately. After data appears, check which queries and pages receive impressions and clicks. Use that information to improve relevant pages, not to insert every phrase into the article.
8. Publish the first article through a reviewable change
Your first article should test the whole system, not just the Markdown renderer.
Before merging it, check:
- The build succeeds.
- The article appears on
/blog. - The article URL loads directly.
- The canonical uses the production domain.
- The title and description match the visible article.
- The sitemap and RSS feed contain the URL.
- Internal links work.
- The page is readable on a phone.
A pull request is useful for the first publication because it makes the new files and structure easy to review. After the deployment, open the production URL and verify it again.
Where SEO Dispatcher helps
SEO Dispatcher is built for this kind of workflow. Add the website first so the app can understand the product and existing pages. When you are ready to publish, connect the repository and review the detected content structure.
For a website without a blog, the publishing change may include the blog structure and the first article. For a website with an existing blog, the safer path is to follow its current folder, extension, and frontmatter conventions.
SEO Dispatcher can prepare the article as Markdown or MDX and send the reviewed change through GitHub. Your existing host still builds and deploys the website; the app is not a second CMS.
The final responsibility stays with the site owner: check the code change, factual claims, metadata, live page, and Search Console setup.