MDSS
Stylesheets for displaying and printing Markdown documents
About
MDSS is a CSS stylesheet to render Markdown documents beautifully both in browsers and in print. You can create your own separate builds for screen and print or a single build for both media.
✨ New in Version 2
- Reworked default design
- Reworked configuration files
- Reworked container classes
- New container classes
- Responsive behavior for columned layouts
- Highlight.js classes are now default for syntax highlighting
- Presets for different kinds of outputs (coming soon)
- Slides are no longer a default media (moved to presets)
- Reworked CLI tool
- Cleaner code
Features
- Formatting HTML documents generated from Markdown
- Fully customizable via variables, custom color palette
- Responsive typography optimized for screens
- Typography optimized for printing documents
- Extra features that can be enabled or disabled
- Syntax highlighting support
- Custom styles using pre-defined variables
- Minified and uncompressed (development) builds
- CLI tool for integration into other projects
Extra Features
The stylesheets include several visual extras by default in addition to standard Markdown elements. All extras can be enabled or disabled for a single build. Extras include the following:
- Automatic nested numbering of headings (available: both media; default: level 1 and 2 heading)
- Automatic numbering of specified elements (e.g. images, tables) (available: both media; default: no elements)
- Automatic URL insertion after links (available: print; default: disabled)
- Replace horizontal rules/thematic breaks with page breaks (available: print; default: enabled)
- Automatic page breaks before specified elements (available: print; default: no elements)
- Avoid page breaks after specified elements (available: print; default: level 1 heading)
- Print only formatted area (available: print, default: disabled)
Markdown Extensions
Various Markdown Extensions that extend the capabilities of the CommonMark compliant Markdown are also supported. In the configuration files you can select what extensions should your build support. Supported extensions include:
- Tables
- Definition lists
- Strikethrough
- Containers
- Containers with text align (default: enabled)
- Floated containers (default: enabled)
- Non-printing containers (default: enabled)
- Flex containers (default: enabled)
- Columned containers (default: 2-4 columns enabled)
- Custom, colored containers (light and dark background) (default: primary, accent and gray colors)
- Sticky containers (default: enabled)
To use these features you need a Markdown compiler that supports transforming their syntax (e.g. pandoc or markdown-it).
Syntax Highlighting
MDSS is created with automatic syntax highlighting in mind and is compatible with syntax highlighting libraries such as highlight.js. The configuration includes options to use the built in syntax highlighting theme with most of syntax highlighters.
Custom syntax highlighting colors can be set for a specific highlighter. There are options to assign colors to syntax highlighting CSS selectors. The default build is configured to work with highlight.js. If you use highlight.js then MDSS can function as a highlight.js style so there is no need for another theme. An alternative configuration is also included in config file's comments to use MDSS with pandoc's default syntax highlighter.
Basic Usage
To use the default bundle build of MDSS you don't even need a download, you can simply link the minified CSS from a CDN like jsdelivr or unpkg. To apply MDSS for your HTML document link it in the <head>
node as a simple stylesheet as it includes media queries.
To create your own build you can clone this repository, edit the configuration a create a new bundle.
git clone https://github.com/vimtaai/mdss
To create a bundled, minified build run the npm run build
command. This will create three stylesheet files, one for each media and one bundled build for both screen and print.
npm installnpm run build
To use MDSS only to format each media individually set the media
property of the link
tag.
<!-- All purpose --><!-- Screen only --><!-- Print only -->
Configuration
Most visual aspects (like color, sizes, spacing) can be configured. The src/config
folder contains all the options to be modified, the rest of the code uses the variables declared here. You can configure each media type individually.
You can also enable/disable all extra features using the src/config/extras.config.scss
file. External resources (e.g. fonts) can be imported by adding them to the src/config/external.config.scss
.
MDSS supports defining a root selector for styling (src/config/shared.config.scss
). If set, only elements inside the root selector get affected by the stylesheet. By default there is no root selector thus the entire document gets formatted. You can also configure the stylesheet to print only the content of the root selector.
Configuration files include the following options:
File | Options |
---|---|
custom.config.scss |
custom styles for each media |
external.config.scss |
external imports (e.g. fonts) |
extras.config.scss |
enable/disable and configure extra features |
print.config.scss |
variables for print styles |
screen.config.scss |
variables for screen styles |
shared.config.scss |
colors, fonts and root selector |
Advanced Usage
MDSS comes with a CLI tool that allows advanced usage with more options. The CLI tool is included as the NPM package's bin
command. You can use the CLI tool with a cloned repository or with an NPM install.
# With git clone git clone https://github.com/vimtaai/mdsscd mdss./bin/mdss.js build # With NPM install npm install mdss./node_modules/.bin/mdss customize./node_modules/.bin/mdss build
If you are using MDSS as an installed NPM package it is recommended to create your own NPM scripts for your common build tasks.
The CLI tool has several options. It allows the creation of bundles that excludes a media type. To see all options see the help of the command in the command line.
./node_modules/.bin/mdss --help./node_modules/.bin/mdss build --help./node_modules/.bin/mdss customize --help
Using with pandoc
MDSS works well with document converters such as pandoc. To create standalone HTML pages that are formatted with MDSS you have to link it in the output document of the pandoc conversion.
pandoc -s path/to/source/file.md -c path/to/mdss/mdss.min.css -o path/to/output/file.html
Note. The path to MDSS has to be relative to the output HTML file.
Creating PDF files
To create PDF documents formatted with MDSS it is recommended to convert to HTML first and use the browser's built in printing dialog to save the result as PDF. Using the printer of the browser will automatically apply the print styles for a bundled build.
Visual Studio Code has an extension called Markdown PDF that supports converting Markdown files to PDF. You can set an MDSS build for print media as the stylesheet for output documents (markdown-pdf.styles
setting). To avoid conflict with the default stylesheet set the markdown-pdf.includeDefaultStyles
setting to false
. For an easy setup add the print stylesheet of MDSS from a CDN. The latest version of Markdown PDF uses puppeteer to create PDF documents so the print media will be automatically applied to the output document.
Prerequisites
You need to have Node.js installed on your computer to create your own bundles.
Contributing
All ideas, recommendations, bug reports, pull requests are welcome. 😄