md2web is a minimalistic, hackable Flask application that renders Markdown files as HTML pages.
demo.webm
- Real-time synchronization between Markdown files and HTML.
- Simple, flexible URL parsing.
- Code highlighting works out-of-the-box.
- Written with hackability and minimalism in mind.
- Clone the project
git clone https://github.com/sinandredemption/md2web.git
- Install dependencies: Navigate to the project directory and install the necessary dependencies.
cd md2web
pip install -r requirements.txt
- Start the server
./start.sh
-
Demo: You can now view the demo website by opening a web browser and navigating to
http://localhost:5000. The website should display the content of the Markdown files in theSample Websitedirectory. -
Make changes: You can modify the content of the Markdown files in the
Sample Websitedirectory and save the changes. Refresh the website to verify that the changes are reflected in real-time.
By default, md2web will serve a website that will give you a good tour of the features and a jist of md2web. The fastest way to get started would be to build your project on top of that website.
The Project has the following structure:
- templates/: This folder contains all the HTML that is generated from the Markdown files.
- Markdown/: This folder contains some sample markdown files. You can put your own Markdown files here or configure md2web to search for markdown in a new folder (see configuration).
- static/: This folder contains styles for the website and code-highlighting.
- templates/__base.html: The base of every page, containing header and footer. Edit to customize to your needs.
- templates/__404.html: Error 404 page.
- app.py: The main Flask app, containing all the routes.
- config: The configuration file.
- config.py: Loads the configuration file in the Flask app.
- md2html.py: Takes in a markdown file and converts it to HTML.
- generate-website.py: Ensures the markdown files and HTML files (and all other files) are in sync. This script is ran at the start of the Flask server.
- start.sh: Start and runs the Flask server.
The config file contains configuration options (in a key=value format). The file config.py acts as the configuration parser. Lines starting with a # character are treated as comments and ignored by the configuration parser.
WebsiteName: The name of the website.PagesPath: The absolute path to the directory where the Markdown files for the website are located.
A sample config with generic defaults is provided.
Frontpage.md is automatically set as the default "home" of your website.
URLs are handled as paths to files inside templates folder, but with a bit more flexibility.
When serving HTML files, md2web ignores all characters except for alpha-numeric characters. This means that if you have a file called My Cool Page!!!.md, the resulting HTML file will be called My Cool Page!!!.html. So, if you want to access that file, you can use the URL /blog/my-cool-page regardless of the exact case of the letters or the presence of spaces or hyphens.
Folders and files in md2web are not case-sensitive. This means that if you have a folder called Blog, you can access it with any combination of upper and lower case letters, such as /blog, /bLog, or /BLOG. The same applies to files within those folders - for example, if you have a file called MyFile.html, you can access it with any combination of upper and lower case letters, such as /blog/myfile, /Blog/Myfile, or /BLOG/MYFILE.
In md2web, the '-' character in URLs is substituted by a space character ' '. So, for example, /blog/my-file and /blog/my file both point to the same file.
If you have non-HTML files in your templates directory, md2web will serve them directly if there is an exact match in the URL. For example, if you have a file called Resume.pdf in your templates directory, you can access it directly with /Resume.pdf.
md2web supports real-time synchronization between files in the PagesPath folder (see section on configuration above) and the served website. This allows users to see changes made to Markdown (or any) files immediately reflected in their browser without the need to manually regenerate the HTML files or the website.
When a file is modified or created in the PagesPath folder, inotifytools detects the change and triggers the regeneration/copying of the corresponding HTML/non-HTML file. The changes are then immediately reflected in the browser upon refreshing the page.
Code highlighting in Markdown documents is handled by the codehilite extension of the Python Markdown library.
To use code highlighting in your Markdown document, you will need to specify the language of the code snippet at the beginning of the code block using the ~~~ syntax. For example, to highlight a block of Python code, you would use the following syntax:
~~~python def hello(): print("Hello, world!") ~~~
Note: Without mentioning the language explicitly, code highlighting is disabled.
The codehilite extension supports a wide range of programming languages, including Python, HTML, CSS, JavaScript, Java, C++, and many others. To see a full list of supported languages, you can refer to the official documentation for the codehilite extension.
The theme for code highlighting is present in static/code.css file. You can customize this or generate new themes using Pygmentize. See CodeHilite's excellent documentation for simple instructions on generating new themes.
This project is licensed under the GPLv3 License - see the LICENSE file for details.