From 9d6d13afa2f519da0affaa3b3be0885e7758ac75 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Sun, 22 Oct 2017 15:37:37 +0200 Subject: [PATCH] Initial documentation and website. --- doc/css.rst | 116 ++++ doc/css/components-test.rst | 545 ++++++++++++++++++ doc/css/components.rst | 861 +++++++++++++++++++++++++++++ doc/css/grid.rst | 349 ++++++++++++ doc/css/page-layout-test.rst | 104 ++++ doc/css/page-layout.rst | 621 +++++++++++++++++++++ doc/css/themes.rst | 105 ++++ doc/css/typography-test.rst | 32 ++ doc/css/typography.rst | 270 +++++++++ doc/examples/article.rst | 20 + doc/examples/jumbo-article.rst | 23 + doc/index.rst | 83 +++ doc/pelican.rst | 99 ++++ doc/pelican/theme-test.rst | 12 + doc/pelican/theme.rst | 407 ++++++++++++++ doc/pelican/writing-content.rst | 417 ++++++++++++++ doc/plugins.rst | 67 +++ doc/plugins/components-test.rst | 165 ++++++ doc/plugins/components.rst | 315 +++++++++++ doc/plugins/htmlsanity-test.rst | 18 + doc/plugins/htmlsanity.rst | 314 +++++++++++ doc/plugins/images-test.rst | 59 ++ doc/plugins/images.rst | 119 ++++ doc/plugins/links.rst | 218 ++++++++ doc/plugins/math-and-code-test.rst | 18 + doc/plugins/math-and-code.rst | 179 ++++++ doc/static/dummy.css | 1 + doc/static/flowers-small.jpg | Bin 0 -> 67897 bytes doc/static/flowers.jpg | Bin 0 -> 186565 bytes doc/static/ship-small.jpg | Bin 0 -> 61650 bytes doc/static/ship.jpg | Bin 0 -> 142488 bytes doc/why.rst | 101 ++++ site/.gitignore | 4 + site/Makefile | 124 +++++ site/content | 1 + site/develop_server.sh | 103 ++++ site/pelicanconf.py | 127 +++++ site/publishconf.py | 17 + 38 files changed, 6014 insertions(+) create mode 100644 doc/css.rst create mode 100644 doc/css/components-test.rst create mode 100644 doc/css/components.rst create mode 100644 doc/css/grid.rst create mode 100644 doc/css/page-layout-test.rst create mode 100644 doc/css/page-layout.rst create mode 100644 doc/css/themes.rst create mode 100644 doc/css/typography-test.rst create mode 100644 doc/css/typography.rst create mode 100644 doc/examples/article.rst create mode 100644 doc/examples/jumbo-article.rst create mode 100644 doc/index.rst create mode 100644 doc/pelican.rst create mode 100644 doc/pelican/theme-test.rst create mode 100644 doc/pelican/theme.rst create mode 100644 doc/pelican/writing-content.rst create mode 100644 doc/plugins.rst create mode 100644 doc/plugins/components-test.rst create mode 100644 doc/plugins/components.rst create mode 100644 doc/plugins/htmlsanity-test.rst create mode 100644 doc/plugins/htmlsanity.rst create mode 100644 doc/plugins/images-test.rst create mode 100644 doc/plugins/images.rst create mode 100644 doc/plugins/links.rst create mode 100644 doc/plugins/math-and-code-test.rst create mode 100644 doc/plugins/math-and-code.rst create mode 100644 doc/static/dummy.css create mode 100644 doc/static/flowers-small.jpg create mode 100644 doc/static/flowers.jpg create mode 100644 doc/static/ship-small.jpg create mode 100644 doc/static/ship.jpg create mode 100644 doc/why.rst create mode 100644 site/.gitignore create mode 100644 site/Makefile create mode 120000 site/content create mode 100755 site/develop_server.sh create mode 100644 site/pelicanconf.py create mode 100644 site/publishconf.py diff --git a/doc/css.rst b/doc/css.rst new file mode 100644 index 00000000..2df810f7 --- /dev/null +++ b/doc/css.rst @@ -0,0 +1,116 @@ +CSS +### + +.. role:: css(code) + :language: css +.. role:: html(code) + :language: html + +The CSS style is the essence of ``m.css``. It makes use of HTML5 tags as much +as possible to avoid redundant classes. Contrary to other popular frameworks, +all custom CSS classes and IDs are prefixed with ``m-`` to avoid conflicts with +3rd party styles. All sizes, paddings and border widths are specified using +``rem`` units, relative to base page font size; :css:`box-sizing: border-box` +is applied to all elements by default. + +`Quick start`_ +============== + +To make full advantage of ``m.css``, you need just three files written in plain +CSS. Download them below or :gh:`grab the whole Git repository `: + +- :gh:`m-grid.css ` with optional + :gh:`m-debug.css ` +- :gh:`m-components.css ` +- :gh:`m-dark.css ` or + :gh:`m-light.css ` + +In addition to the above, if you want to present highlighted code snippets on +your website, there's also a builtin style for `Pygments `_, +matching ``m.css`` themes: + +- :gh:`pygments-dark.css `, + generated from :gh:`pygments-dark.py ` + +Once you have the files, include them in your HTML markup. The top-level +``m-dark.css`` / ``m-light.css`` file includes the other via CSS :css:`@import` +statement, so you don't need to reference these. The dark theme uses the +`Source Sans Pro `_ font for +copy and `Source Code Pro `_ +font for pre-formatted text and code, which you need to reference as well. See +the `Themes <{filename}/css/themes.rst>`_ page for requirements of other +themes. + +Besides that, in order to have devices recognize your website properly as +responsive and not zoom it all the way out to an unreadable mess, don't forget +to include a proper :html:`` tag. The HTML5 DOCTYPE is also required. + +.. code:: html + + + + + + + + + ... + + +.. block-warning:: Browser compatibility + + Note that some older browsers have problems with CSS variables and + :css:`@import` statements. Because of that, the builtin themes provide + a ``*.compiled.css`` versions that are *post*\ processed without CSS + variables or :css:`@import` statements. The compiled version includes also + the Pygments style, all combined in one file: + + - :gh:`m-dark.compiled.css ` + (:filesize:`{filename}/../css/m-dark.compiled.css`, + :filesize-gz:`{filename}/../css/m-dark.compiled.css` compressed) + - :gh:`m-light.compiled.css ` + (:filesize:`{filename}/../css/m-light.compiled.css`, + :filesize-gz:`{filename}/../css/m-light.compiled.css` compressed) + + I recommend using the original files for development and switching to the + compiled versions when publishing the website. + +With this, you can start using the framework right away. Click the headings +below to get to know more. + +`Grid system » <{filename}/css/grid.rst>`_ +========================================== + +The ``m-grid.css`` file provides a 12-column layout, inspired by +`Bootstrap `_. It provides a simple, easy-to-use +solution for modern responsive web development. It comes together with +``m-debug.css`` that helps debugging the most common mistakes in grid layouts. + +`Typography » <{filename}/css/typography.rst>`_ +=============================================== + +Sane default style for body text, paragraphs, lists, links, headings and other +common typographical elements, provided by the ``m-components.css`` file. + +`Components » <{filename}/css/components.rst>`_ +=============================================== + +The ``m-components.css`` file also contains styles for visual elements that add +more structure to your content. From simple notes and topic blocks, tables, +images or figures to complex elements like code snippets, math formulas or +image grid. + +`Page layout » <{filename}/css/page-layout.rst>`_ +================================================= + +Besides that, ``m-components.css`` has also full-fledged collection of elements +to form not only the content, but the whole page including navigation --- +header and footer, section headings, article styling with sidebar and tag cloud +and more. + +`Themes » <{filename}/css/themes.rst>`_ +======================================= + +Finally, ``m-dark.css`` and ``m-light.css`` use CSS variables to achieve easy +theming. Two builtin themes, used by the author himself on a bunch of websites +to guarantee that everything fits well together. diff --git a/doc/css/components-test.rst b/doc/css/components-test.rst new file mode 100644 index 00000000..254c8d0d --- /dev/null +++ b/doc/css/components-test.rst @@ -0,0 +1,545 @@ +Test +#### + +:save_as: css/components/test/index.html +:breadcrumb: {filename}/css.rst CSS + {filename}/css/components.rst Components + +Blocks +====== + +.. raw:: html + +
+
+
+

Default block

+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Link. +
+
+
+
+

Primary block

+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Link. +
+
+
+
+

Success block

+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Link. +
+
+
+
+

Warning block

+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Link. +
+
+
+
+

Danger block

+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Link. +
+
+
+
+

Info block

+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Link. +
+
+
+
+

Dim block

+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Link. +
+
+
+ +Notes, frame +============ + +.. raw:: html + +
+
+
+

Default note

+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Link. +
+
+
+
+

Primary note

+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Link. +
+
+
+
+

Success note

+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Link. +
+
+
+
+

Warning note

+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Link. +
+
+
+
+

Danger note

+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Link. +
+
+
+
+

Info note

+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Link. +
+
+
+
+

Dim note

+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Link. +
+
+
+
+

Frame

+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Link. +
+
+
+ +Text +==== + +.. raw:: html + +

Default text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Aliquam pharetra imperdiet tortor sed vehicula. Link.

+

Primary text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Aliquam pharetra imperdiet tortor sed vehicula. Link.

+

Success text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Aliquam pharetra imperdiet tortor sed vehicula. Link.

+

Warning text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Aliquam pharetra imperdiet tortor sed vehicula. Link.

+

Danger text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Aliquam pharetra imperdiet tortor sed vehicula. Link.

+

Info text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Aliquam pharetra imperdiet tortor sed vehicula. Link.

+

Dim text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Aliquam pharetra imperdiet tortor sed vehicula. Link.

+ +Tables +====== + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table caption
#HeadingSecond
heading
1CellSecond cell
22nd row cell2nd row 2nd cell
ΣFooterSecond
footer
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Full-width table
#Heading textHeading textHeading textHeading textHeading textHeading text
1Cell contentsCell contentsCell contentsCell contentsCell contentsCell contents
2Cell contentsCell contentsCell contentsCell contentsCell contentsCell contents
3Cell contentsCell contentsCell contentsCell contentsCell contentsCell contents
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Default rowLoremipsumdolorsitametLink
Primary rowLoremipsumdolorsitametLink
Success rowLoremipsumdolorsitametLink
Warning rowLoremipsumdolorsitametLink
Danger rowLoremipsumdolorsitametLink
Info rowLoremipsumdolorsitametLink
Dim rowLoremipsumdolorsitametLink
Default cellLinkLoremipsumdolorsitamet
Primary cellLinkLoremipsumdolorsitamet
LoremSuccess cellLinkipsumdolorsitamet
LoremipsumWarning cellLinkdolorsitamet
LoremipsumdolorDanger cellLinksitamet
LoremipsumdolorsitInfo cellLinkamet
LoremipsumdolorsitametDim cellLink
Default headerLinkLoremipsumdolorsitamet
Primary headerLinkLoremipsumdolorsitamet
LoremSuccess headerLinkipsumdolorsitamet
LoremipsumWarning headerLinkdolorsitamet
LoremipsumdolorDanger headerLinksitamet
LoremipsumdolorsitInfo headerLinkamet
LoremipsumdolorsitametDim headerLink
+ +Images +====== + +Image, centered: + +.. raw:: html + + + +Image, centered, link: + +.. raw:: html + +
+ +
+ +Image, fullwidth (yes, it should be pixelated): + +.. raw:: html + + + +Image, fullwidth, link (yes, it should be pixelated): + +.. raw:: html + +
+ +
+ +Figures +======= + +Figure, centered: + +.. raw:: html + +
+ +
A Ship
+
Photo © The Author
+
+ +Figure, centered, image link, flat: + +.. raw:: html + +
+ +
A Ship
+
Photo © The Author
+
+ +Figure, fullwidth, without description (yes, it should be pixelated): + +.. raw:: html + +
+ +
A Ship
+
+ +Image grid +========== + +Without the link: + +.. raw:: html + +
+
+
+ +
F9.0, 1/250 s, ISO 100
+
+
+ +
F2.8, 1/1600 s, ISO 100
+
+
+
+ +With link, without caption, not inflated: + +.. raw:: html + +
+
+
+ + +
+ +
+
+ + +
+ +
+
+
+ +Without link or caption: + +.. raw:: html + +
+
+
+ +
+
+
+ +
+
+
+
+ +`Code figure`_ +============== + +A flat code figure: + +.. raw:: html + +
+ 
Some
+        code
+    snippet
+ And a resulting output. +
+ +A code figure with :html:`
` in description. Activating the section header
+should not affect it.
+
+.. raw:: html
+
+    

+        
Some
+        code
+    snippet

+        
And a resulting output.

+    

diff --git a/doc/css/components.rst b/doc/css/components.rst
new file mode 100644
index 00000000..5d7a5369
--- /dev/null
+++ b/doc/css/components.rst
@@ -0,0 +1,861 @@
+Components
+##########
+
+:breadcrumb: {filename}/css.rst CSS
+
+``m.css`` provides a set of basic components for further improving the layout
+and display of authored content.
+
+.. contents::
+    :class: m-block m-default
+
+`Colors`_
+=========
+
+Similarly to Bootstrap, ``m.css`` has a set of predefined colors that affect
+how a certain component looks. This works on majority of components shown on
+this page. The colors are:
+
+-   :css:`.m-default` is a default style that doesn't grab attention
+-   :css:`.m-primary` is meant to be used to highlight the primary element on a
+    page
+-   :css:`.m-success` is good to highlight happy things
+-   :css:`.m-warning` catches attention, but doesn't hurt
+-   :css:`.m-danger` brings really bad news
+-   :css:`.m-info` is for side notes
+-   :css:`.m-dim` is shy and doesn't want you to be bothered by the information
+    it brings
+
+`Blocks`_
+=========
+
+Blocks, defined by :css:`.m-block`, wrap the content in a light frame and add a
+bolder colored bar on the left. Use in combination with one of the color styles
+above. Block caption should go into :html:`
` and is colored in respect to
+the color style as well. Text and links always have the default color, except
+for :css:`.m-block.m-dim`. It's also possible to have a block without the
+border, just add :css:`.m-flat` class to it.
+
+.. code-figure::
+
+    .. code:: html
+
+        

+          
Default block

+          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices
+          a erat eu suscipit. Link.
+        

+
+    .. raw:: html
+
+        

+          

+            

+              
Default block

+              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Link.
+            

+          

+          

+            

+              
Primary block

+              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Link.
+            

+          

+          

+            

+              
Success block

+              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Link.
+            

+          

+          

+            

+              
Warning block

+              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Link.
+            

+          

+          

+            

+              
Danger block

+              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Link.
+            

+          

+          

+            

+              
Info block

+              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Link.
+            

+          

+          

+            

+              
Dim block

+              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Link.
+            

+          

+          

+            

+              
Flat block

+              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Link.
+            

+          

+        

+
+`Notes, frame`_
+===============
+
+Unlike blocks, notes are meant to wrap smaller bits of information. Use the
+:css:`.m-note` CSS class together with desired color class. A note is also
+slightly rounded and has everything colored, the background, the caption, text
+and also links. The :html:`
` caption tag is optional.
+
+Besides notes, there is a frame element defined by :css:`.m-frame`, which just
+wraps your content in a slightly rounded border. No color classes apply to a
+frame.
+
+.. code-figure::
+
+    .. code:: html
+
+        

+          
Success note

+          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Link.
+        

+
+    .. raw:: html
+
+        

+          

+            

+              
Default note

+              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Link.
+            

+          

+          

+            

+              
Primary note

+              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Link.
+            

+          

+          

+            

+              
Success note

+              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Link.
+            

+          

+          

+            

+              
Warning note

+              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Link.
+            

+          

+          

+            

+              
Danger note

+              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Link.
+            

+          

+          

+            

+              
Info note

+              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Link.
+            

+          

+          

+            

+              
Dim note

+              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Link.
+            

+          

+          

+            

+              
Frame

+              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Link.
+            

+          

+        

+
+`Text`_
+=======
+
+Use :css:`.m-text` CSS class together with desired color class to color a
+paragraph or inline text.
+
+.. code-figure::
+
+    .. code:: html
+
+        
Warning text. Lorem ipsum dolor sit amet,
+        consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Aliquam
+        pharetra imperdiet tortor sed vehicula. Link.

+
+    .. raw:: html
+
+        

+          

+            
Default text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Aliquam pharetra imperdiet tortor sed vehicula. Link.

+          

+          

+            
Primary text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Aliquam pharetra imperdiet tortor sed vehicula. Link.

+          

+          

+            
Success text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Aliquam pharetra imperdiet tortor sed vehicula. Link.

+          

+          

+            
Warning text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Aliquam pharetra imperdiet tortor sed vehicula. Link.

+          

+          

+            
Danger text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Aliquam pharetra imperdiet tortor sed vehicula. Link.

+          

+          

+            
Info text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Aliquam pharetra imperdiet tortor sed vehicula. Link.

+          

+          

+            
Dim text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus ultrices a erat eu suscipit. Aliquam pharetra imperdiet tortor sed vehicula. Link.

+          

+        

+
+Apply :css:`.m-small` or :css:`.m-big` CSS class together with :css:`.m-text`
+to make the text appear smaller or larger.
+
+.. code-figure::
+
+    .. code:: html
+
+        
Larger text. Lorem ipsum dolor sit amet, consectetur
+        adipiscing elit. Vivamus ultrices a erat eu suscipit. Aliquam pharetra
+        imperdiet tortor sed vehicula.

+        
Smaller text. Lorem ipsum dolor sit amet, consectetur
+        adipiscing elit. Vivamus ultrices a erat eu suscipit. Aliquam pharetra
+        imperdiet tortor sed vehicula.

+
+    .. raw:: html
+
+        
Larger text. Lorem ipsum dolor sit amet, consectetur
+        adipiscing elit. Vivamus ultrices a erat eu suscipit. Aliquam pharetra
+        imperdiet tortor sed vehicula.

+        
Smaller text. Lorem ipsum dolor sit amet, consectetur
+        adipiscing elit. Vivamus ultrices a erat eu suscipit. Aliquam pharetra
+        imperdiet tortor sed vehicula.

+
+`Button links`_
+===============
+
+To highlight important links such as file download, you can style them as
+buttons. Use :css:`.m-button` CSS class together with desired color class on an
+:html:`` tag. The button is by default displayed as inline block, either
+wrap it in :css:`.m-text-center` etc. :html:`
` to make it centered or
+apply a :css:`.m-fullwidth` class to it to display it as a full-width block
+with center-aligned label.
+
+.. code-figure::
+
+    .. code:: html
+
+        Success button
+
+    .. raw:: html
+
+        

+          

+            Default button
+          

+          

+            Primary button
+          

+          

+            Success button
+          

+          

+            Warning button
+          

+          

+            Danger button
+          

+          

+            Info button
+          

+          

+            Dim button
+          

+        

+
+You can put two :html:`
`\ s with :css:`.m-big` and :css:`.m-small` CSS
+class inside the :html:`` to achieve the following effect:
+
+.. code-figure::
+
+    .. code:: html
+
+        

+          
+            
Download the thing

+            
Any platform, 5 kB.

+          
+        

+
+    .. raw:: html
+
+        

+          
+            
Download the thing

+            
Any platform, 5 kB.

+          
+        

+
+`Tables`_
+=========
+
+Use :css:`.m-table` to apply styling to a table. The table is centered by
+default; rows are separated by lines, with :html:`` and :html:``
+being separated by a thicker line. Rows are highlighted on hover, :html:``
+is rendered in bold, all :html:`` and :html:`` are aligned to left
+while table :html:`` is centered. Example table:
+
+.. code-figure::
+
+    .. code:: html
+
+        
+          
+          
+            
+              
+              
+              
+            
+          
+          
+            
+              
+              
+              
+            
+          
+          
+            
+              
+              
+              
+            
+          
+          
+            
+              
+              
+              
+            
+          
+        
Table caption
#HeadingSecond
heading
1CellSecond cell
22nd row cell2nd row 2nd cell
ΣFooterSecond
footer

+
+    .. raw:: html
+
+        
+          
+          
+            
+              
+              
+              
+            
+          
+          
+            
+              
+              
+              
+            
+          
+          
+            
+              
+              
+              
+            
+          
+          
+            
+              
+              
+              
+            
+          
+        
Table caption
#HeadingSecond
heading
1CellSecond cell
22nd row cell2nd row 2nd cell
ΣFooterSecond
footer

+
+Similarly to other components, you can color particular :html:`` or
+:html:`` elements using the color classes from above:
+
+.. raw:: html
+
+    

+      
+        
+          
+          
+          
+          
+          
+          
+          
+        
+        
+          
+          
+          
+          
+          
+          
+          
+        
+        
+          
+          
+          
+          
+          
+          
+          
+        
+        
+          
+          
+          
+          
+          
+          
+          
+        
+        
+          
+          
+          
+          
+          
+          
+          
+        
+        
+          
+          
+          
+          
+          
+          
+          
+        
+        
+          
+          
+          
+          
+          
+          
+          
+        
+      
+    
Default rowLoremipsumdolorsitametLink
Primary rowLoremipsumdolorsitametLink
Success rowLoremipsumdolorsitametLink
Warning rowLoremipsumdolorsitametLink
Danger rowLoremipsumdolorsitametLink
Info rowLoremipsumdolorsitametLink
Dim rowLoremipsumdolorsitametLink

+
+`Images`_
+=========
+
+Putting :css:`.m-image` class onto the :html:`` tag makes it centered,
+slightly rounded and sets its max width to 100%. Adding :css:`.m-fullwidth` on
+the image element works as expected. For accessibility reasons it's a good
+practice to include the ``alt`` attribute.
+
+.. code-figure::
+
+    .. code:: html
+
+        Flowers
+
+    .. raw:: html
+
+        Flowers
+
+To make the image clickable, wrap the :html:`` tag in an additional
+:html:`
` and put the :css:`.m-image` class on the :html:`
` element
+instead of on the image. This will ensure that only the image is clickable and
+not the surrounding area:
+
+.. code-figure::
+
+    .. code:: html
+
+        

+          
+        

+
+    .. raw:: html
+
+        

+          
+        

+
+`Figures`_
+==========
+
+Use the HTML5 :html:`
` tag together with :css:`.m-figure` to style it.
+As with plain image, it's by default centered, slightly rounded and has a
+border around the caption and description. The caption is expected to be in the
+:html:`
` element. The description is optional, but should be
+wrapped in some tag as well (for example a :html:`
`). The
+:css:`.m-fullwidth` class works here too and you can also wrap the
+:html:`` element in an :html:`` tag to make it clickable.
+
+Figure always expects at least the caption to be present. If you want just an
+image, use the plain image tag. If you have a lot of figures on the page and
+the border is distracting, apply the :css:`.m-flat` class to hide it.
+
+.. code-figure::
+
+    .. code:: html
+
+        

+          Ship
+          
A Ship

+          
+        

+
+    .. raw:: html
+
+        

+          Ship
+          
A Ship

+          
Photo © The Author

+        

+
+`Image grid`_
+=============
+
+Inspired by `image grids on Medium `_,
+its purpose is to present photos in a beautiful way. Wrap one or more
+:html:`
` elements in a :html:`
` element and
+delimit each row with a wrapper :html:`
`. Each :html:`
` element
+needs to contain an :html:`` and a :html:`
` with image caption
+that appears on hover; these two elements can be optionally wrapped in an
+:html:`` to make the image clickable. If you don't want a caption, use an
+empty :html:`
` instead of :html:`
`. If you want the grid to
+`inflate to full container width <{filename}/css/grid.rst#inflatable-nested-grid>`_,
+add a :css:`.m-container-inflate` CSS class to it.
+
+.. note-warning::
+
+    The inner :html:`
` or :html:`
` element is *important*,
+    without it the grid won't look as desired.
+
+Example usage (stupidly showing the two images all over again --- sorry):
+
+.. code:: html
+
+    

+      
+      
+    

+
+.. raw:: html
+
+    

+      
+      
+    

+
+The core idea behind the image grid is scaling particular images to occupy the
+same height on given row. First, a sum :math:`W` of image aspect ratios is
+calculated for the whole row:
+
+.. math::
+
+    W = \sum_{i=0}^{n-1} \cfrac{w_i}{h_i}
+
+Then, percentage width :math:`p_i` of each image is calculated as:
+
+.. math::
+
+    p_i = W \cfrac{w_i}{h_i} \cdot 100 \%
+
+.. note-info::
+
+    The image width calculation is quite annoying to do manually, that's why
+    ``m.css`` provides a `Pelican plugin <{filename}/plugins/images.rst#image-grid>`_
+    that does the hard work for you.
+
+`Code`_
+=======
+
+``m.css`` recognizes code highlighting compatible with `Pygments `_
+and provides additional styling for it. There's a set of builtin `pygments-*.css <{filename}/css.rst>`_
+styles that match the ``m.css`` themes.
+
+For example, code highlighted using:
+
+.. code:: sh
+
+    echo -e "int main() {\n    return 0;\n}" | pygmentize -f html -l c++ -O nowrap
+
+Will spit out a bunch of :html:`` elements like below. To create a code
+block, wrap the output in :html:`
` (note that whitespace
+matters inside this tag):
+
+.. code-figure::
+
+    .. code:: html
+
+        
int main() {
+            return 0;
+        }

+
+    .. raw:: html
+
+        
int main() {
+            return 0;
+        }

+
+Pygments allow to highlight arbitrary lines, which affect the rendering in this
+way:
+
+.. code:: c++
+    :hl_lines: 2 3
+
+    int main() {
+        std::cout << "Hello world!" << std::endl;
+        return 0;
+    }
+
+Sometimes you want to focus on code that has been changed / added and mute the
+rest. Add an additional :css:`.m-inverted` CSS class to the
+:html:`
` to achieve this effect:
+
+.. code:: c++
+    :hl_lines: 4 5
+    :class: m-inverted
+
+    #include 
+
+    int main() {
+        std::cout << "Hello world!" << std::endl;
+        return 0;
+    }
+
+To have code highlighting inline, wrap the output in :html:``
+instead of :html:`
`:
+
+.. code-figure::
+
+    .. code:: html
+
+        
The main()
+        function doesn't need to have a return
+        statement.

+
+    .. raw:: html
+
+        
The main()
+        function doesn't need to have a return
+        statement.

+
+.. note-success::
+
+    To make your life easier, ``m.css`` provides a
+    `Pelican plugin <{filename}/plugins/math-and-code.rst#code>`__
+    that integrates Pygments code highlighting as a :abbr:`reST `
+    directive.
+
+`Code figure`_
+==============
+
+It often happens that you want to present code with corresponding result
+together. The code figure looks similar to `image figures <#figures>`_ and
+consists of a :html:`
` element containing a
+:html:`
` block and whatever else you want to put in as the result. The
+:html:`
` element has to be the very first child of the :html:`
`
+for the markup to work correctly. Similar to image figure, you can apply the
+:css:`.m-flat` CSS class to remove the border.
+
+Example (note that this page uses code figure for all code examples, so it's a
+bit of a figure inception shown here):
+
+.. code-figure::
+
+    .. code:: html
+
+        

+          
Some
+            code
+        snippet

+          And a resulting output.
+        

+
+    .. raw:: html
+
+        

+          
Some
+            code
+        snippet

+          And a resulting output.
+        

+
+`Math`_
+=======
+
+:html:`` elements containing math can be wrapped in
+:html:`
` to make it centered. `CSS color classes <#colors>`_
+can be applied to the :html:`
` as well. It's a good practice to include
+:html:`` and :html:`<description>` elements for accessibility reasons.
+
+.. code-figure::
+
+    .. code:: html
+
+        <div class="m-math m-success">
+          <svg>
+            <title>LaTeX Math 
+            a^2 = b^2 + c^2
+            ...
+          
+        

+
+    .. raw:: html
+
+        

+          
+            LaTeX Math
+            a^2 = b^2 + c^2
+            
+              
+              
+              
+              
+              
+              
+            
+            
+              
+              
+              
+              
+              
+              
+              
+              
+            
+          
+        

+
+For inline math, add the :css:`.m-math` class to the :html:`` tag
+directly. Note that you'll probably need to manually specify
+:css:`vertical-align` style to make the formula align well with surrounding
+text. You can use CSS color classes here as well.
+
+.. code-figure::
+
+    .. code:: html
+
+        
There is a movement for replacing circle
+        constant ... with the
+        ... character.
+
+    .. raw:: html
+
+        
There is a movement for replacing
+        circle constant 
+          LaTeX Math
+          2 \pi
+          
+            
+            
+          
+          
+            
+            
+          
+         with the 
+          LaTeX Math
+            \tau
+          
+            
+          
+          
+            
+          
+         character.

+
+.. note-warning::
+
+    Producing SVG manually using command-line tools is no fun, so ``m.css``
+    provides a `Pelican plugin <{filename}/plugins/math-and-code.rst#math>`__
+    that integrates latex math directly into your markup. Check it out!
+
+`Padding`_
+==========
+
+Similarly to `typography elements <{filename}/css/typography.rst#padding>`_;
+blocks, notes, frames, tables, images, figures, image grids, code and math
+blocks and code figures have :css:`1rem` padding after, except when they are
+the last element, to avoid excessive spacing.
+
+`Responsive utilities`_
+=======================
+
+If you have some element that will certainly overflow on smaller screen sizes
+(such as wide table or image that can't be scaled), wrap it in a
+:css:`.m-scroll`. This will put a horizontal scrollbar under in case the
+element overflows.
+
+There's also :css:`.m-fullwidth` that will make your element always occupy 100%
+of the parent element width. Useful for tables or images.
+
+.. note-dim::
+    :class: m-text-center
+
+    `« Typography <{filename}/css/typography.rst>`_ | `CSS <{filename}/css.rst>`_ | `Page layout » <{filename}/css/page-layout.rst>`_
diff --git a/doc/css/grid.rst b/doc/css/grid.rst
new file mode 100644
index 00000000..7fd2b449
--- /dev/null
+++ b/doc/css/grid.rst
@@ -0,0 +1,349 @@
+Grid system
+###########
+
+:breadcrumb: {filename}/css.rst CSS
+
+.. role:: css(code)
+    :language: css
+
+Inspired by `Bootstrap `_, the grid system is the
+heart of a responsive website layout. The `m-grid.css <{filename}/css.rst>`_
+file contains all the setup you need for it. Besides that, in order to have
+devices recognize your website properly as responsive and not zoom it out all
+the way to an unreadable mess, don't forget to add this to your :html:``:
+
+.. code:: html
+
+    
+
+.. contents::
+    :class: m-block m-default
+
+`Overview`_
+===========
+
+If you have never heard of it, it all boils down to a few breakpoints that
+define how the website is wide on various screen sizes. For every one of them
+you can define how your page and content layout will look like. In every case
+you have 12 columns and it's completely up to you how you use them. Let's start
+with an example.
+
+.. code:: html
+
+    

+      

+        
.m-col-t-6

+        
.m-col-t-6

+      

+      

+        
.m-col-s-4 .m-col-m-6

+        
.m-col-s-4 .m-col-m-3

+        
.m-col-s-4 .m-col-m-3

+      

+      

+        
.m-col-l-7

+        
.m-col-l-5

+      

+    

+
+.. raw:: html
+
+    

+      
.m-col-t-6

+      
.m-col-t-6

+    

+    

+      
.m-col-s-4 .m-col-m-6

+      
.m-col-s-4 .m-col-m-3

+      
.m-col-s-4 .m-col-m-3

+    

+    

+      
.m-col-l-7

+      
.m-col-l-5

+    

+
+.. note-info::
+
+    To see the effect, try to resize your browser window (or rotate the screen
+    of your mobile device). Please note that the live examples here are not
+    *exactly* matching the code --- I added a bunch of HTML elements and CSS
+    classes to improve clarity.
+
+In the above code, the outer :html:`
` is taking care
+of limiting the website layout width. On very narrow devices, the whole screen
+width is used, on wider screens fixed sizes are used in order to make the
+content layouting manageable. The :css:`.m-container` usually has :css:`.m-row`
+items directly inside, but that's not a requirement --- you can put anything
+there, if you just want to have some predictable width limitation to your
+content.
+
+The :html:`
` denotes a row. The row is little more than
+a delimiter for columns --- it just makes sure that two neighboring rows don't
+interact with each other in a bad way.
+
+The actual magic is done by the row elements denoted by :css:`.m-col-B-N`. The
+``B`` is one of four breakpoints --- ``t`` for tiny, ``s`` for small, ``m`` for
+medium and ``l`` for large --- based on screen width. The ``N`` is number of
+columns that given element will span. So, looking at the code above,
+:css:`.m-col-m-3` will span three columns out of twelve on medium-sized screen.
+
+This setting is inherited upwards --- if you specify a column span for a
+smaller screen width, it will get applied on larger width as well, unless you
+override it with a setting for larger screen width. On the other hand, if given
+screen width has no column width specified, the element will span the whole
+row. So, again from above, the :css:`.m-col-s-4 .m-col-m-6` element will span
+the whole row on tiny screen sizes, four columns on small screen sizes and six
+columns on medium and large screen sizes.
+
+`Detailed grid properties`_
+===========================
+
+.. class:: m-table
+
++-------------------+-----------------------+---------------------------+-------------------------------+
+| Breakpoint        | Screen width range    | ``.m-container`` width    | Classes applied, ordered by   |
+|                   | (inclusive)           |                           | priority                      |
++===================+=======================+===========================+===============================+
+| ``t``, "tiny",    | less than 576px       | full screen width         | ``.m-col-t-*``                |
+| portrait phones   |                       |                           |                               |
++-------------------+-----------------------+---------------------------+-------------------------------+
+| ``s``, "small",   | 576px - 767px         | 560px                     | ``.m-col-s-*``,               |
+| landscape phones  |                       |                           | ``.m-col-t-*``                |
++-------------------+-----------------------+---------------------------+-------------------------------+
+| ``m``, "medium",  | 768px - 991px         | 750px                     | ``.m-col-m-*``,               |
+| tablets, small    |                       |                           | ``.m-col-s-*``,               |
+| desktops          |                       |                           | ``.m-col-t-*``                |
++-------------------+-----------------------+---------------------------+-------------------------------+
+| ``l``, "large",   | 992px and up          | 960px                     | ``.m-col-l-*``,               |
+| desktops, very    |                       |                           | ``.m-col-m-*``,               |
+| large tablets     |                       |                           | ``.m-col-s-*``,               |
+|                   |                       |                           | ``.m-col-t-*``                |
++-------------------+-----------------------+---------------------------+-------------------------------+
+
+`Wrapping around`_
+==================
+
+Besides the above "all or nothing" scenario, where all the elements either form
+a single row or are laid out one after another in separate rows, it's possible
+to wrap the items around so they for example take four columns in a large
+screen width and two rows of two columns in a small screen width. In such case
+it's important to account for elements with different heights using a
+:css:`.m-clearfix-*` for given breakpoint:
+
+.. code:: html
+
+    

+      

+        
.m-col-s-6 .m-col-m-3
...
...

+        
.m-col-s-6 .m-col-m-3

+        

+        
.m-col-s-6 .m-col-m-3
...

+        
.m-col-s-6 .m-col-m-3
...

+      

+    

+
+.. raw:: html
+
+    

+      
.m-col-s-6 .m-col-m-3
...
...

+      
.m-col-s-6 .m-col-m-3

+      

+      
.m-col-s-6 .m-col-m-3
...

+      
.m-col-s-6 .m-col-m-3
...

+    

+
+.. note-success::
+
+    Shrink your browser window and then try to remove the
+    :html:`
` element to see what it does in the above
+    markup.
+
+`Pushing and pulling`_
+======================
+
+It's possible to push and pull the elements around using :css:`.m-push-*` and
+:css:`.m-pull-*` and even use this functionality to horizontally reorder
+content based on screen width. Learn by example:
+
+.. code:: html
+
+    

+      

+        
.m-col-l-6 .m-push-l-3

+      

+      

+        
.m-col-s-8 .m-push-s-4
first

+        
.m-col-s-4 .m-pull-s-8
second

+      

+    

+
+.. raw:: html
+
+    

+      
.m-col-l-6 .m-push-l-3

+    

+    

+      
.m-col-s-8 .m-push-s-4
first

+      
.m-col-s-4 .m-pull-s-8
second

+    

+
+.. note-warning::
+
+    There may be some corner cases related to column span inheritance and
+    pushing/pulling. If the output is not desired, try specifying the
+    :css:`.m-push-*` and :css:`.m-pull-*` explicitly for all breakpoints.
+
+`Floating around`_
+==================
+
+It's also possible to responsively float or align the elements around using
+:css:`m-left-*`, :css:`m-right-*` and :css:`m-center-*` if you put the
+:css:`.m-col-*` elements directly into text flow without wrapping them in a
+:css:`.m-row` element. The following example will float the contents to the
+right on medium-size screens, center them on small and put them full-width
+on tiny screens:
+
+.. code:: html
+
+    

+      .m-col-s-6 .m-center-s .m-col-m-4 .m-right-m
+    

+    
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+    tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
+    quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+    consequat.

+
+.. frame::
+
+    .. raw:: html
+
+        

+        
.m-col-s-6 .m-center-s .m-col-m-4 .m-right-m

+        

+        
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+        tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
+        quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+        consequat.

+
+.. note-info::
+
+    The floating works on any element, not just those that are :css:`.m-col-*`.
+
+`Grid padding`_
+===============
+
+The :css:`.m-container` element pads its contents from left and right by
+:css:`1rem`; the :css:`.m-row` adds a negative :css:`-1rem` margin on left and
+right to reset it. Finally, the :css:`.m-col-*` elements have :css:`1rem`
+padding on all sides to separate the contents. It's possible to override this
+on the :css:`.m-container` and/or on :css:`.m-col-*` elements using
+:css:`.m-nopad`, :css:`.m-nopadx`, :css:`m-nopady`, :css:`.m-nopadt`,
+:css:`.m-nopadb`, :css:`.m-nopadl`, :css:`.m-nopadr` which remove all, just
+horizontal or vertical padding, or padding on the top/bottom/left/right,
+respectively.
+
+`Grid nesting`_
+===============
+
+It's possible to nest the grid. Just place a :css:`.m-row` element inside an
+:css:`.m-col-*` (it *doesn't* need to be a direct child) and put your
+:css:`.m-col-*` elements inside. The inner grid will also have 12 columns, but
+smaller ones.
+
+.. note-info::
+
+    Because the :css:`.m-container` element specifies a fixed width, it's not
+    desirable to wrap the nested grid with it again.
+
+`Removing the grid on larger screen sizes`_
+===========================================
+
+The usual behavior is to *add* the grid for larger screen sizes, but sometimes
+you might want to do the opposite. It's possible to do that just by specifying
+:css:`.m-col-*-12` for given breakpoint, but sometimes the CSS :css:`float`
+property might cause problems. The :css:`.m-col-*-none` classes completely
+remove all grid-related CSS styling for given screen size and up so the element
+behaves like in its initial state.
+
+.. code:: html
+
+    

+      

+        
.m-col-s-8 .m-col-l-none

+        
.m-col-s-4 .m-col-l-none

+      

+    

+
+.. raw:: html
+
+    

+      
.m-col-s-8 .m-col-l-none

+      
.m-col-s-4 .m-col-l-none

+    

+
+`Hiding elements based on screen size`_
+=======================================
+
+The :css:`.m-show-*` and :css:`.m-hide-*` classes hide or show the element on
+given screen size and up. Useful for example to show a different kind of
+navigation on different devices.
+
+.. code:: html
+
+    
.m-show-m
shown on M and up

+    
.m-hide-l
hidden on L and up

+
+.. raw:: html
+
+    

+        
.m-show-m
shown on M and up

+        
.m-hide-l
hidden on L and up

+    

+
+`Inflatable nested grid`_
+=========================
+
+It's usual that the content area of the page doesn't span the full 12-column
+width in order to avoid long unreadable lines. But sometimmes one might want to
+use the full available width --- for example to show big pictures or to fit
+many things next to each other.
+
+If you have a ten-column content area with one column space on each side, mark
+your :css:`.m-container` element with :css:`#m-container-inflatable` and then
+put your nested content in elements marked with :css:`.m-container-inflate`.
+
+.. code:: html
+
+    

+      

+        

+          
.m-container-inflate

+        

+      

+    

+
+.. raw:: html
+
+    
.m-container-inflate

+
+`Debug CSS`_
+============
+
+It's sometimes hard to see why the layout isn't working as expected. Including
+the `m-debug.css <{filename}/css.rst>`_ file will highlight the most usual
+mistakes --- such as :css:`.m-row` not directly containing :css:`.m-col-*` or
+two :css:`.m-container`\ s nested together --- with bright red background for
+you to spot the problems better:
+
+.. code:: html
+
+    
+
+Other than highlighting problems, this file doesn't alter your website
+appearance in any way. To save unnecessary requests and bandwidth, I recommend
+that you remove the reference again when publishing the website.
+
+.. note-dim::
+    :class: m-text-center
+
+    `CSS <{filename}/css.rst>`_ | `Typography » <{filename}/css/typography.rst>`_
diff --git a/doc/css/page-layout-test.rst b/doc/css/page-layout-test.rst
new file mode 100644
index 00000000..5d95c472
--- /dev/null
+++ b/doc/css/page-layout-test.rst
@@ -0,0 +1,104 @@
+Test
+####
+
+:save_as: css/page-layout/test/index.html
+:breadcrumb: {filename}/css.rst CSS
+             {filename}/css/page-layout.rst Page layout
+
+`Components in highlighted sections`_
+=====================================
+
+Click on the section header above to see the effect. Left border radius on all
+elements should be flattened and nothing should jump when highlighted.
+
+.. note-default::
+
+    Default note
+
+.. note-primary::
+
+    Primary note
+
+.. note-success::
+
+    Success note
+
+.. note-warning::
+
+    Warning note
+
+.. note-danger::
+
+    Danger note
+
+.. note-info::
+
+    Info note
+
+.. note-dim::
+
+    Dim note
+
+`Subsections`_
+--------------
+
+.. code:: c++
+
+    int main() { }
+
+.. block-default:: Default block
+
+    Blocks don't change their appearance much.
+
+.. block-flat:: Flat block
+
+    Flat blocks don't change their appearance at all.
+
+.. frame:: Frame
+
+    Frame will have its left border fattened.
+
+`Nested components`_
+--------------------
+
+Shouldn't be any difference.
+
+.. container:: m-row
+
+    .. container:: m-col-m-4 m-col-s-6
+
+        .. note-default::
+
+            Default note.
+
+    .. container:: m-col-m-4 m-col-s-6
+
+        .. block-primary:: Primary block
+
+            Text.
+
+    .. container:: m-col-m-4 m-col-s-6
+
+        .. frame::
+
+            A frame.
+
+    .. container:: m-clearfix-m
+
+        ..
+
+    .. container:: m-col-m-4 m-col-s-6
+
+        .. code:: hs
+
+            :: -> :: -> ::
+
+    .. container:: m-col-m-4 m-col-s-6
+
+        .. class:: m-inverted-highlight
+        .. code:: c++
+            :hl_lines: 2
+
+            int main() {
+                return 666;
+            }
diff --git a/doc/css/page-layout.rst b/doc/css/page-layout.rst
new file mode 100644
index 00000000..bbd9bee1
--- /dev/null
+++ b/doc/css/page-layout.rst
@@ -0,0 +1,621 @@
+Page layout
+###########
+
+:breadcrumb: {filename}/css.rst CSS
+
+.. role:: raw-html(raw)
+   :format: html
+
+.. role:: sh(code)
+    :language: sh
+
+Besides separate components, ``m.css`` provides a fully-fledged whole page
+layout, including top navigation bar, footer navigation, article styling and
+more.
+
+.. contents::
+    :class: m-block m-default
+
+`Basic markup structure`_
+=========================
+
+A barebones HTML markup structure using ``m.css`` looks like below. There is
+the usual preamble, with :html:`` and a :html:`` tag
+specifying the file encoding. Some browsers assume UTF-8 by default (as per the
+`HTML5 standard `__), but some
+not, so it's better to always include it. In the :html:``
+element it's important to also specify that the site is responsive via the
+:html:`` tag.
+
+The :html:`` element is divided into three parts --- top navigation bar,
+main page content and the footer navigation, explained below. Their meaning is
+implicit, so it's not needed to put any CSS classes on these elements, but you
+have to stick to the shown structure.
+
+.. code:: html
+
+    
+    
+      
+        Page title
+        
+        
+        
+      
+      
+        

+        

+          
+        

+        

+      
+    
+
+`Theme color`_
+==============
+
+Some browsers (such as Vivaldi or Chrome on Android) are able to color the
+tab based on page theme color. This can be specified using the following
+:html:`` tag. The color shown matches the default (dark) style, see the
+`CSS themes <{filename}/css/themes.rst>`_ page for colors matching other
+themes.
+
+.. code:: html
+
+    
+
+`Top navigation bar`_
+=====================
+
+The top navigation bar is linear on
+`medium and larger screens <{filename}/css/grid.rst#detailed-grid-properties>`__
+and hidden under a "hamburger menu" on smaller screens. It has a distinct
+background that spans the whole window width, but the content is limited to
+page width as defined by the grid system.
+
+A very simple navigation bar with a homepage link and three additional menu
+items is shown below.
+
+.. code:: html
+
+    

+
+The :css:`#m-navbar-brand` element is positioned on the left, in the default
+dark theme shown in bold and uppercase. On medium and large screens, the
+contents of :css:`#m-navbar-collapse` are shown, linearly, aligned to the right.
+
+On small and tiny screens, the :css:`#m-navbar-show` and :css:`#m-navbar-hide`
+show the :raw-html:`☰` glyph aligned to the right instead of
+:css:`#m-navbar-collapse`. Clicking on this "hamburger menu" icon will append
+either ``#navigation`` or ``#`` to the page URL, which triggers the
+:css:`#m-navbar-collapse` element to be shown under as a list or hidden again.
+
+.. note-info::
+
+    You can change the :css:`#navigation` ID to a different name, if you want,
+    for example for localization --- it won't do any harm to the functionality.
+    Just be sure that the :html:`` part is updated as
+    well.
+
+`Two-column navigation on small screens`_
+-----------------------------------------
+
+To save vertical space on small screens, it's possible to split the navbar
+contents into two (or more) columns using standard ``m.css``
+`grid functionality <{filename}/css/grid.rst>`_:
+
+.. code:: html
+    :hl_lines: 7 8 9 10 11 12 13 14 15 16 17 18 19
+    :class: m-inverted
+
+    

+
+`Sub-menus in the navbar`_
+--------------------------
+
+For each menu item it's also possible to add single-level sub-menu. On larger
+screens the menu will be shown on hover, on small screens the sub-menu will
+appear as an indented sub-list.
+
+.. code:: html
+    :hl_lines: 15 16 17 18 19 20 21
+    :class: m-inverted
+
+    

+
+`Active menu item highlighting`_
+--------------------------------
+
+Add :css:`#m-navbar-current` ID to the :html:`` element of a menu item
+that's currently active to highlight it. This works for both top-level menu
+items and sub-menus. Doesn't do anything on the :css:`#m-navbar-brand` element.
+
+.. note-success::
+
+    See the top of the page for live example of all navbar features and view
+    page source to see how it's done here. Don't forget to try to shrink your
+    browser window to see its behavior in various cases.
+
+`Footer navigation`_
+====================
+
+The :html:`