Write responsive web UIs in plain Markdown syntax.
Markdown-UI translates extended Markdown into fully styled Fomantic-UI HTML — buttons, forms, grids, modals, and 60+ other components — with no knowledge of HTML or CSS required.
Project website: http://jjuliano.github.io/markdown-ui/
- Requirements
- Installation
- Usage
- Interactive Shell (REPL)
- Version Configuration
- Local Assets
- Supported Components
- Syntax Quick Reference
- Notes / Known Limitations
- Credits
- Contributing
- Ruby 3.0 or newer
- Bundler 2.7+
Install the gem from RubyGems:
gem install markdown-uiPass a Markdown file and redirect standard output to produce an HTML file:
markdown-ui index.md > index.htmlThe generated HTML includes a full <!DOCTYPE html> document that loads Fomantic-UI and jQuery from a CDN by default.
Usage: markdown-ui [options] [markdown_file]
If no file is provided, interactive mode is started.
Options:
-i, --interactive Start interactive shell mode
--interactive-html Generate full HTML in interactive mode
--local-assets Use local npm packages instead of CDN
--fomantic-version VERSION Specify Fomantic UI version (default: 2.9.3)
--jquery-version VERSION Specify jQuery version (default: 3.7.1)
-h, --help Show this help message
-v, --version Show version
Start the built-in read-evaluate-print loop to experiment with Markdown-UI syntax in real time:
$ markdown-ui --interactive
MarkdownUI Interactive Shell
Commands:
- Type markdown and press ENTER three times to parse
- 'exit', 'quit', or 'bye' to exit
- 'help' for this message
- 'clear' to clear the screen
- 'version' for version information
Start typing your markdown...
markdown> __button|A Button__
#
#
Rendered output:
==================================================
<button class="ui button">A Button</button>
==================================================
Add --interactive-html to receive a complete HTML document instead of a bare snippet:
markdown-ui --interactive --interactive-htmlFomantic-UI and jQuery CDN versions can be overridden via environment variables or CLI flags.
Environment variables (source .markdown-ui-versions for a ready-made template):
export MARKDOWN_UI_FOMANTIC_VERSION=2.9.3 # default
export MARKDOWN_UI_JQUERY_VERSION=3.7.1 # defaultCommand-line flags (take precedence over environment variables):
markdown-ui --fomantic-version 2.9.3 --jquery-version 3.7.1 index.md > index.htmlSupported version ranges: Fomantic-UI 2.8.0+, jQuery 3.6.0+.
When deploying to an environment without internet access, install Fomantic-UI and jQuery via npm and serve assets locally:
npm install fomantic-ui jquery
markdown-ui --local-assets index.md > index.htmlThe --local-assets flag rewrites all asset references to /node_modules/… paths instead of CDN URLs.
See COMPONENTS.md for the full syntax reference. The table below lists every supported component by category.
| Component | Component | Component |
|---|---|---|
| Buttons | Containers | Dividers |
| Emojis | Fields | Flags |
| Headers | Icons | Images |
| Inputs | Labels | Loaders |
| Placeholders | Rails | Reveals |
| Segments | Steps | Text |
| Component | Component | Component |
|---|---|---|
| Breadcrumbs | Forms | Grids |
| Menus | Messages | Tables |
| Component | Component | Component |
|---|---|---|
| Accordions | Calendars | Checkboxes |
| Dimmers | Dropdowns | Embeds |
| Flyouts | Modals | Nags |
| Popups | Progress | Ratings |
| Search | Shapes | Sidebars |
| Sliders | Sticky | Tabs |
| Toasts | Transitions |
| Component | Component | Component |
|---|---|---|
| Advertisements | Cards | Comments |
| Feeds | Items | Statistics |
| Behavior | Behavior | Behavior |
|---|---|---|
| API | State | Visibility |
Below are the most common patterns. See COMPONENTS.md for the full list.
__button|Click Me__
__primary button|Save__
__icon|home__
__label|New__
__input|Enter text__
__segment|Content goes here__
__message|Hello world__
__progress|75__> Container:
> > Grid:
> > > Column:
> > > Content for column one
> > > Column:
> > > Content for column two:smile: :heart: :thumbsup: :fire:> Menu:
> [Home](#)
> [About](#about)
> [Contact](#contact)
> > Right Menu:
> > [Login](#login)- Ongoing component support — new Fomantic-UI components are added incrementally; check TODO.md for status.
- Colon character — a bare
:inside body text is interpreted as a block-element separator; use:or a full-width colon：for literal colons (e.g. in URLs). - Block-element spacing — a
<!-- -->comment or a blank line with two spaces is required between sibling block elements (e.g. adjacent columns). - JavaScript-dependent components — some Fomantic-UI components (e.g. toggle buttons, modals, dropdowns) require JavaScript to function. Embed a
<script>block alongside your Markdown-UI source to initialise them.
Markdown-UI is built on top of two excellent open-source projects:
- Fomantic-UI — the community-maintained fork of Semantic-UI that provides all CSS components and JavaScript behaviours.
- RedCarpet — the fast and flexible Markdown parser that drives the rendering pipeline.
A huge thanks to the contributors behind both projects.
- Fork the repository ( https://github.com/jjuliano/markdown-ui/fork )
- Create a feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Open a Pull Request
Please run the test suite before submitting:
bundle exec rake test