# Introduction
MdPress is composed of two parts: a minimalistic site generator with a React-powered theming system and Plugin API, and a default theme optimized for writing technical documentation. It was created to support the documentation needs of docschina’s own sub projects.
Each page generated by MdPress has its own pre-rendered static HTML, providing great loading performance and is SEO-friendly. Yet, once the page is loaded, React takes over the static content and turns it into a full Single-Page Application (SPA). Extra pages are fetched on demand as the user navigates around the site.
If your page data is stored on the service side, you can also render them by writing specific plugins.
# How It Works
A MdPress site is in fact a SPA powered by React、React Router and Webpack. If you’ve used React before, you will notice the familiar development experience when you are writing or developing custom themes (you can even use React DevTools to debug your custom theme!).
During the build, we create a server-rendered version of the app and render the corresponding HTML by virtually visiting each route. This approach is inspired by Nuxt's nuxt generate
command and other projects like Gatsby and Vuepress.
Each Markdown file is compiled into HTML with markdown-it and then processed as the template of a React component. This allows you to directly use React inside your Markdown files and is great when you need to embed dynamic content.
# Features
Built-in Markdown extensions
Using React in Markdown
React-powered custom theme system
Default theme
- Responsive layout
- Optional Homepage
- Simple out-of-the-box header-based search
- Algolia Search
- Customizable navbar and sidebar
- Auto-generated GitHub link and page edit links
- PWA: Popup UI to refresh contents
- Last Updated
- Multi-Language Support
Plugin
# Why Not ...?
# Vuepress
Vuepress have a great design, and this project use for reference its design and code, but it only renders Markdown stored in the local file system, not Markdown stored on the service side.
# Nuxt
Nuxt is capable of doing what MdPress does, but it’s designed for building applications. MdPress is focused on content-centric sites and provides features tailored for technical documentation out of the box.
# Docsify / Docute
Both are great projects are both fully runtime-driven and therefore not SEO-friendly. If you don’t care for SEO and don’t want to mess with installing dependencies, these are still great choices.
# Hexo
in fact, we are probably still a long way to go from migrating away from it for our main site. The biggest problem is that its theming system is static and string-based - we want to take advantage of React for both the layout and the interactivity. Also, Hexo’s Markdown rendering isn’t the most flexible to configure.
# GitBook
The primary problem with GitBook is that its development reload performance is intolerable with a large amount of files. The default theme also has a pretty limiting navigation structure, and the theming system is, again, not React based. The team behind GitBook is also more focused on turning it into a commercial product rather than an open-source tool.