.. 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.
+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
+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 <mosra/m.css>`:
- :gh:`m-grid.css <mosra/m.css$master/css/m-grid.css>` with optional
In addition to the above, if you want to present highlighted code snippets on
your website, there's also a builtin style for `Pygments <http://pygments.org/>`_,
-matching ``m.css`` themes:
+matching m.css themes:
- :gh:`pygments-dark.css <mosra/m.css$master/css/pygments-dark.css>`,
generated from :gh:`pygments-dark.py <mosra/m.css$master/css/pygments-dark.py>`
`« Typography <{filename}/css/typography.rst>`_ | `CSS <{filename}/css.rst>`_ | `Page layout » <{filename}/css/page-layout.rst>`_
-``m.css`` provides a set of basic components for further improving the layout
-and display of authored content.
+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:
+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
.. 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>`_
+ 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 <http://pygments.org/>`_
+m.css recognizes code highlighting compatible with `Pygments <http://pygments.org/>`_
and provides additional styling for it. There's a set of builtin `pygments-*.css <{filename}/css.rst>`_
-styles that match the ``m.css`` themes.
+styles that match the m.css themes.
For example, code highlighted using:
.. note-success::
- To make your life easier, ``m.css`` provides a
+ 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 <reStructuredText>`
directive.
.. note-warning::
- Producing SVG manually using command-line tools is no fun, so ``m.css``
+ 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!
.. 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.
+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:`<html lang="en">` and a :html:`<meta>` tag
+A barebones HTML markup structure using m.css looks like below. There is the
+usual preamble, with :html:`<html lang="en">` and a :html:`<meta>` tag
specifying the file encoding, which should be the first thing in :html:`<head>`.
Some browsers assume UTF-8 by default (as per the
`HTML5 standard <https://www.w3schools.com/html/html_charset.asp>`__), but some
-----------------------------------------
To save vertical space on small screens, it's possible to split the navbar
-contents into two (or more) columns using standard ``m.css``
+contents into two (or more) columns using standard m.css
`grid functionality <{filename}/css/grid.rst>`_:
.. code:: html
crowded. It's meant to be used for navigation, but besides that it gives you a
complete freedom. As an example, you can populate it with four columns (which
become two columns on narrow screens) of navigation and a fine print, using
-just the builtin ``m.css`` grid features:
+just the builtin m.css grid features:
.. code:: html
The :html:`<main>` content is separated from the header and footer by
:css:`1rem` padding, besides that there is no additional implicit styling. It's
-recommended to make use of ``m.css`` `grid features <{filename}/css/grid.rst>`_
-for content layout --- in particular, the :html:`<main>` element by itself
-doesn't even put any width restriction on the content.
+recommended to make use of m.css `grid features <{filename}/css/grid.rst>`_ for
+content layout --- in particular, the :html:`<main>` element by itself doesn't
+even put any width restriction on the content.
-To follow HTML5 semantic features, ``m.css`` expects you to put your main page
+To follow HTML5 semantic features, m.css expects you to put your main page
content into an :html:`<article>` element, be it an article or not. Heading is
always in an :html:`<h1>` inside the article element, sub-sections are wrapped
in nested :html:`<section>` elements with :html:`<h2>` and further. Example
----------------
Besides usual pages, which have the :html:`<article>` element filled with
-:html:`<h1>` followed by a wall of content, ``m.css`` has first-class support
-for landing pages. The major component of a landing page is a cover image in
-the background, spanning the whole page width in a :css:`#m-landing-image`
-element. The image is covered by :css:`#m-landing-cover` element that blends
-the image into the background on the bottom. On top of it you have full freedom
-to put any layout you need, for example a logo, a short introductionary
-paragraph and a download button. Note that the grid setup has to only wrap the
-content "below the fold", *not* the cover image.
+:html:`<h1>` followed by a wall of content, m.css has first-class support for
+landing pages. The major component of a landing page is a cover image in the
+background, spanning the whole page width in a :css:`#m-landing-image` element.
+The image is covered by :css:`#m-landing-cover` element that blends the image
+into the background on the bottom. On top of it you have full freedom to put
+any layout you need, for example a logo, a short introductionary paragraph and
+a download button. Note that the grid setup has to only wrap the content "below
+the fold", *not* the cover image.
.. code:: html
`Articles`_
-----------
-For blog-like articles, ``m.css`` provides styling for article header, summary
-and footer --- just put :html:`<header>` and :html:`<footer>` elements directly
+For blog-like articles, m.css provides styling for article header, summary and
+footer --- just put :html:`<header>` and :html:`<footer>` elements directly
into the surrounding :html:`<article>` tag. Article header is rendered in a
bigger and brighter font, while footer is rendered in a smaller and dimmer
font. Example markup and corresponding rendering:
.. role:: css(code)
:language: css
-``m.css`` provides two themes, a dark and a light one. A theme consists of just
-a set of CSS variables, which affect fonts, colors and other properties. The
-theme file is also an self-contained entry point for the whole ``m.css``
-framework --- it includes all the other necessary CSS files except fonts via
-CSS :css:`@import` statements.
+m.css provides two themes, a dark and a light one. A theme consists of just a
+set of CSS variables, which affect fonts, colors and other properties. The
+theme file is also an self-contained entry point for the whole m.css framework
+--- it includes all the other necessary CSS files except fonts via CSS
+:css:`@import` statements.
.. block-warning:: Browser support
:language: css
Right after being responsive, typography is the second most important thing in
-``m.css`` and so the most often used HTML elements are styled to make them look
+m.css and so the most often used HTML elements are styled to make them look
great by default.
.. contents::
`Pelican <https://getpelican.com/>`_ is a static site generator powered by
Python and unlike most other static site generators, it uses
`reStructuredText <http://docutils.sourceforge.net/rst.html>`_ instead of
-Markdown for authoring content. ``m.css`` provides a theme for it, together
-with a set of useful plugins.
+Markdown for authoring content. m.css provides a theme for it, together with a
+set of useful plugins.
.. note-warning::
==============
Install Pelican either via ``pip`` or using your system package manager. Note
-that in order to use ``m.css`` `plugins <{filename}/plugins.rst>`_ later, you
-may want to install the Python 3 version.
+that in order to use m.css `plugins <{filename}/plugins.rst>`_ later, you may
+want to install the Python 3 version.
.. code:: sh
=========================================
A feature-packed theme with modern and responsive design that exposes all of
-``m.css`` functionality with goodies on top such as social meta tags,
-breadcrumb navigation and more.
+m.css functionality with goodies on top such as social meta tags, breadcrumb
+navigation and more.
.. role:: rst(code)
:language: rst
-The second largest offering of ``m.css`` is a full-featured theme for the
+The second largest offering of m.css is a full-featured theme for the
`Pelican static site generator <https://getpelican.com/>`_. The theme is
designed to fit both the use case of a simple blog consisting of just articles
or a full product/project/portfolio website where the blog is only a side dish.
==============
The easiest way to start is putting the :gh:`whole Git repository <mosra/m.css>`
-of ``m.css`` into your project, for example as a submodule:
+of m.css into your project, for example as a submodule:
.. code:: sh
The most minimal configuration to use the theme is the following. Basically you
need to tell Pelican where the theme resides (it's in the ``pelican-theme/``
-subdir of your ``m.css`` submodule), then you tell it to put the static
-contents of the theme into a ``static/`` directory in the root of your
-webserver; the ``CSS_FILES`` variable is a list of CSS files that the theme
-needs. You can put there any files you need, but there need to be at least the
-files mentioned on the `CSS themes <{filename}/css/themes.rst>`_ page. Lastly,
-the theme uses some Jinja2 filters from the `m.htmlsanity <{filename}/plugins/htmlsanity.rst>`_
+subdir of your m.css submodule), then you tell it to put the static contents of
+the theme into a ``static/`` directory in the root of your webserver; the
+``CSS_FILES`` variable is a list of CSS files that the theme needs. You can put
+there any files you need, but there need to be at least the files mentioned on
+the `CSS themes <{filename}/css/themes.rst>`_ page. Lastly, the theme uses some
+Jinja2 filters from the `m.htmlsanity <{filename}/plugins/htmlsanity.rst>`_
plugin, so that plugin needs to be loaded as well.
.. code:: py
------------------------
It's common for pages to be organized in a hierarchy and the user should be
-aware of it. ``m.css`` Pelican theme provides breadcrumb navigation, which is
+aware of it. m.css Pelican theme provides breadcrumb navigation, which is
rendered in main page heading (as described in the
`CSS page layout <{filename}/css/page-layout.rst#breadcrumb-navigation>`__
documentation) and also in page title. Breadcrumb links are taken from the
.. note-warning::
- The ``m.css`` Pelican theme doesn't provide per-year, per-month or per-day
+ The m.css Pelican theme doesn't provide per-year, per-month or per-day
archive pages or category, tag, author *list* pages at the moment. List of
categories and tags is available in a sidebar from any article or article
listing page.
.. note-info::
Please note that the above example code uses some directives provided by
- ``m.css`` `Pelican plugins <{filename}/plugins.rst>`_ that are not builtin
- in the :abbr:`reST <reStructuredText>` parser itself.
+ m.css `Pelican plugins <{filename}/plugins.rst>`_ that are not builtin in
+ the :abbr:`reST <reStructuredText>` parser itself.
`Interpreted text roles`_
-------------------------
directive will automatically make a Table of Contents list out of headings
in your document. Very useful for navigation in large pages and articles.
-For stuff like images, figures, code blocks, math listing etc., ``m.css``
-provides `Pelican plugins <{filename}/plugins.rst>`_ that do it better than the
-builtin way. Head over to the official :abbr:`reST <reStructuredText>`
-documentation for `more info about builtin directives <http://docutils.sourceforge.net/docs/ref/rst/directives.html>`_.
+For stuff like images, figures, code blocks, math listing etc., m.css provides
+`Pelican plugins <{filename}/plugins.rst>`_ that do it better than the builtin
+way. Head over to the official :abbr:`reST <reStructuredText>` documentation
+for `more info about builtin directives <http://docutils.sourceforge.net/docs/ref/rst/directives.html>`_.
`Essential interpreted text roles`_
===================================
- It's also possible to put raw HTML code inline by deriving from the
`raw <http://docutils.sourceforge.net/docs/ref/rst/roles.html#raw>`__ role.
-Again, ``m.css`` provides `Pelican plugins`_ that allow you to have inline
-code, math, GitHub and Doxygen links and much more. Head over to the official
+Again, m.css provides `Pelican plugins`_ that allow you to have inline code,
+math, GitHub and Doxygen links and much more. Head over to the official
:abbr:`reST <reStructuredText>` documentation for
`more info about builtin roles <http://docutils.sourceforge.net/docs/ref/rst/roles.html>`_.
.. role:: py(code)
:language: py
-The `Pelican theme <{filename}/pelican/theme.rst>`_ provided by ``m.css``
-uses only a part of the functionality on its own, the rest is exposed by
-various plugins.
+The `Pelican theme <{filename}/pelican/theme.rst>`_ provided by m.css uses only
+a part of the functionality on its own, the rest is exposed by various plugins.
`Usage`_
========
`HTML sanity » <{filename}/plugins/htmlsanity.rst>`_
====================================================
-The :py:`m.htmlsanity` plugin is essential for ``m.css``. It makes your markup
+The :py:`m.htmlsanity` plugin is essential for m.css. It makes your markup
valid HTML5, offers a few opt-in typographical improvements and enables you to
make full use of features provided by other plugins.
.. role:: css(code)
:language: css
-Most of ``m.css`` `CSS components <{filename}/css/components.rst>`_ are exposed
-to Pelican via custom :abbr:`reST <reStructuredText>` directives. Unlike with
-pure CSS, the directives are *not* prefixed with ``m-`` to save some typing ---
+Most of m.css `CSS components <{filename}/css/components.rst>`_ are exposed to
+Pelican via custom :abbr:`reST <reStructuredText>` directives. Unlike with pure
+CSS, the directives are *not* prefixed with ``m-`` to save some typing ---
which is the most important thing when authoring content.
.. contents::
directives and:
- Adds :css:`.m-image` / :css:`.m-figure` CSS classes to them so they have
- the expected ``m.css`` `image <{filename}/css/components.rst#images>`_ and
+ the expected m.css `image <{filename}/css/components.rst#images>`_ and
`figure <{filename}/css/components.rst#figures>`_ styling.
- Removes the :rst:`:align:`, :rst:`:figwidth:` and :rst:`:scale:` options,
- as this is better handled by ``m.css`` features.
+ as this is better handled by m.css features.
- To maintain accessibility easier, makes it possible to enforce :rst:`:alt:`
text for every image and figure by setting :py:`M_IMAGES_REQUIRE_ALT_TEXT`
to :py:`True`.
.. role:: rst(code)
:language: rst
-``m.css`` plugins make linking to external content almost too easy. If your
-website is about coding, chances are quite high that you will be linking to
+m.css plugins make linking to external content almost too easy. If your website
+is about coding, chances are quite high that you will be linking to
repositories, documentation or bugtrackers. Manually copy-pasting links from
the browser gets quite annoying after a while and also doesn't really help with
keeping the reST sources readable.
The plugin overrides the builtin Pelican
`abbr interpreted text role <http://docs.getpelican.com/en/stable/content.html#file-metadata>`_
and makes its syntax consistent with other common roles of :abbr:`reST <reStructuredText>`
-and ``m.css``.
+and m.css.
Use the :rst:`:abbr:` interpreted text role for creating abbreviations with
title in angle brackets:
.. note-info::
- Well, while ``m.css`` itself doesn't *need* JavaScript, it doesn't prevent
- you from using it -- put in as many jQueries as you want.
+ Well, while m.css itself doesn't *need* JavaScript, it doesn't prevent
+ *you* from using it -- put in as many jQueries as you want.
Why no CSS preprocessors?
=========================
your main work is presenting websites. So remove the unneeded hassle of paying
extra for a dynamic webhosting, installing and maintaining a huge CMS and
patching it twice a month for a neverending stream new CVEs. Together with
-`Pelican <{filename}/pelican.rst>`_, ``m.css`` provides a solution harnessing
-the endless possibilities of your local machine to generate a bunch of static
-HTML files, which you can then upload *anywhere*. And as a bonus, you have the
-full control over your content --- nothing's hidden in opaque databases.
+`Pelican <{filename}/pelican.rst>`_, m.css provides a solution harnessing the
+endless possibilities of your local machine to generate a bunch of static HTML
+files, which you can then upload *anywhere*. And as a bonus, you have the full
+control over your content --- nothing's hidden in opaque databases.
.. note-success::
- This is all optional, though --- ``m.css`` can work with a dynamic CMS
- below as well. Or with your hand-written HTML. Not sure about WYSIWYG
- editors, tho.
+ This is all optional, though --- m.css can work with a dynamic CMS below as
+ well. Or with your hand-written HTML. Not sure about WYSIWYG editors, tho.
Why Pelican and not Jekyll or ...?
==================================
Contributions welcome, though! Does it look like I'm not putting enough
effort in? Submit an improvement! Make a difference
- :gh:`over at GitHub <mosra/m.css/issues/new>`. Both the ``m.css`` code and
+ :gh:`over at GitHub <mosra/m.css/issues/new>`. Both the m.css code and
contents of this site are public, available under the MIT license.
~cjwatson / blog.git / commitdiff