Perplex Theme
  • News
  • Docs
  • Blog
  • About
  • GitHub

Category: Markdown

The Intuitive Markup Language

  • Markdown logo
    • Docs
    • ›
    • TL;DR

    Markdown Layout

    Samples of Hugo’s extended CommonMark syntax to give a quick impression of the layout capabilities.

    • Georg Makowski
    • Docs
    • ›
    • Intro

    Markdown

    Markdown has become the favored markup language to structure text files. With good cause: Markdown syntax is simple.

    • Georg Makowski
  • Newspaper page with lots of different headings
    • Docs
    • ›
    • Basic

    Text Headings

    Headings introduce and order the segments on a page. We can modify headings only visually to adhere to a strict HTML hierarchy while enhancing the design.

    • Georg Makowski
  • Some paragraphs of text
    • Docs
    • ›
    • Basic

    Paragraphs

    Paragraphs are the essential building blocks of text. A comfortable line length and surrounding whitespace contribute to their legibility.

    • Georg Makowski
  • A page in a book with a lot of line breaks
    • Docs
    • ›
    • Basic

    Line Break

    Sometimes we like to begin a new line without starting a whole new text block. Placing such a hard-line break gets complicated when hard-line wraps control the line length inside our Markdown files.

    • Georg Makowski
  • The word “Bold” in bold letters
    • Docs
    • ›
    • Basic

    Emphasis

    We have two types of emphasis to accentuate segments of our content: Light emphasis or strong emphasis. And we can nest both types.

    • Georg Makowski
  • The quote “All ideas grow out of other ideas” written on a a large stairway
    • Docs
    • ›
    • Basic

    Quote

    To quote someone means to recognize her or his thoughts as part of our own. We may agree or disagree, but we should refer to them correctly.

    • Georg Makowski
  • A small notebook with a list
    • Docs
    • ›
    • Basic

    Simple List

    A simple list is unordered and groups a set of related items. Any item may contain a sub-list.

    • Georg Makowski
  • An old wooden library database
    • Docs
    • ›
    • Basic

    Ordered List

    Ordered lists group related items and mark them with ascending counters. They provide a very clear structure for a relatively short number of items.

    • Georg Makowski
  • Code on a screen
    • Docs
    • ›
    • Basic

    Code

    The main text column offers space for 80 characters of code in one line. When we need 120 to fit in one line, we can choose to additionally use the marginal column.

    • Georg Makowski
  • Straight condensation trail behind an airplane
    • Docs
    • ›
    • Basic

    Horizontal Rule

    Sometimes the separation of page segments by space is not clear enough. Then we can add this layout element as an explicit visual separation.

    • Georg Makowski
  • A few chain links
    • Docs
    • ›
    • Basic

    Links

    Internet references or short “links” are the binding fabric of the web. Markdown encourages their use by providing a few 
    simple markup options.

    • Georg Makowski
  • Splashing ring of water
    • Docs
    • ›
    • Basic

    Image

    The CommonMark image syntax is simple and the theme additionally distinguishes between two possible image positions: stand-alone & embedded.

    • Georg Makowski
  • Movable type for printing letters
    • Docs
    • ›
    • Basic

    Special Characters

    All available characters are valid Markdown. The following sections are about the special ones we can’t use directly.

    • Georg Makowski
  • A few entries in a printed dictionary
    • Docs
    • ›
    • Extended

    Definition List

    Definition lists consist of terms as list markers, which are associated with details in the list entries.

    • Georg Makowski
  • A book with a lot of hand-written notes
    • Docs
    • ›
    • Extended

    Footnotes

    Footnotes are best suited for (formal) information, which is not essential for the meaning of the text.

    • Georg Makowski
  • A detail from a large data list
    • Docs
    • ›
    • Extended

    Tables

    Markdown tables need some care, because their layout breaks, when the content of one row exceeds the available width.

    • Georg Makowski
  • A few colored pencils
    • Docs
    • ›
    • Extended

    Strike-through and Insertion

    Correction marks highlight changes while working on a draft. Lately, strike-through has also become a hip visual style.

    • Georg Makowski
  • Hand written task list
    • Docs
    • ›
    • Extended

    Task List

    A task list on a web page should be an interactive element which directly changes the corresponding Markdown. A theme can’t establish such a connection on its own.

    • Georg Makowski
  • Some specimen of movable type for printing
    • Docs
    • ›
    • Extended

    Typographer

    Simple ASCII punctuation characters are substituted with the typographic correct ones.

    • Georg Makowski
  • Big diagram on the walls of a room
    • Docs
    • ›
    • Extended

    GoAT

    GoAT renders ASCII diagrams as SVG and is a Golang implementation of Markdeep’s ASCII renderer.

    • bridge structure
      • Docs
      • ›
      • Improved
      • ›
      • Image

      Extended Image Syntax

      To alter the appearance we can pass additional parameters.

      • Georg Makowski
    • A splashing drop of water
      • Docs
      • ›
      • Improved
      • ›
      • Image

      Stand-alone Image

      This page demonstrates the layout for advanced stand-alone images. For the Markdown syntax see basic image and extended image. Tiny Tiny ¼ 1. Tiny figure(gm) “Who am taking the ebonics quiz?”, the prof jovially axed. Few black taxis drive up major roads on quiet hazy nights. Vamp fox held quartz duck just by wing. Sex-charged fop blew my junk TV quiz. A quivering Texas zombie fought republic linked jewelry. Joaquin Phoenix was gazed by MTV for luck.
      • Georg Makowski
    • Splashing ring of water
      • Docs
      • ›
      • Improved
      • ›
      • Image

      Embedded image (float)

      This page demonstrates the layout for advanced embedded images. For the Markdown syntax see basic image and extended image. At the beginning Normal size Normal ½ embedded 1. Normal size(gm) Quick zephyrs blow, vexing daft Jim. A wizard’s job is to vex chumps quickly in fog. A quick movement of the enemy will jeopardize six gunboats. Twelve ziggurats quickly jumped a finch box. Amazingly few discotheques provide jukeboxes. My girl wove six dozen plaid jackets before she quit.
      • Georg Makowski
    • Complicated image
      • Docs
      • ›
      • Improved
      • ›
      • Image

      Image Processing

      The theme relies solely on Hugo’s image-processing capabilities.

      • Georg Makowski
    • Christmas decoration
      • Docs
      • ›
      • Improved
      • ›
      • Attributes

      How to use Attributes?

      Hugo’s attributes are plain HTML attributes getting injected from the Markdown source into the rendered HTML.

      • Georg Makowski
    • Cardboard boxes
      • Docs
      • ›
      • Improved
      • ›
      • Attributes

      Boxes

      There is one box for framing content like a figure. And there are four kinds of annotation boxes for important messages: Danger, warning, info, and success.

      • Georg Makowski
    • big arrow to the right
      • Docs
      • ›
      • Improved
      • ›
      • Attributes

      Position & Size

      When the content of a block fits nicely into a single column we can shrink & move it in the layout.

      • Georg Makowski
    • The anchor of a ship
      • Docs
      • ›
      • Improved
      • ›
      • Attributes

      Anchors

      It’s easy to manually add anchors to any block element with an identifier attribute and to reference them with a Markdown link.

      • Georg Makowski
    • Clear water
      • Docs
      • ›
      • Improved
      • ›
      • Attributes

      Clear a floating element

      Sometimes we want the text to stop floating around an embedded element. Then we have to place a good ol’ .clear attribute.

      • Georg Makowski
    • Old inventory listing
      • Docs
      • ›
      • Improved
      • ›
      • Attributes

      Attribute Register

      All element-specific attributes are listed here to provide a kind of cheat sheet.

      • Georg Makowski
    • A HTML tag
      • Docs
      • ›
      • Improved
      • ›
      • Replacements

      How to use replacements

      Text enclosed by curly braces { and } and special ASCII signs is replaced with missing Markdown tags after rendering. x{‍^3} for example gets turned into x3.

      • Georg Makowski
    • Blackboard with Einsteins most famous formula
      • Docs
      • ›
      • Improved
      • ›
      • Replacements

      Super-, Subscripts and Fractions

      For occasional vertically shifted characters, these replacement codes are sufficient.

      • Georg Makowski
    • Open red marker
      • Docs
      • ›
      • Improved
      • ›
      • Replacements

      Mark

      Mark and highlight inline text as especially important.

      • Georg Makowski
    • An old typewriter with cactuses growing inside
      • Docs
      • ›
      • Improved
      • ›
      • Replacements

      Keyboard Legend

      Refer explicitly to keyboard strokes in your text.

      • Georg Makowski
    • A sign on a tree cites Martin Luther King in French: “Croyez en vos rêves et ils se réaliseront peut-être. Croyez en vous et ils se réaliseron sûrement.”
      • Docs
      • ›
      • Improved
      • ›
      • Replacements

      Referencing the work of others

      This replacement code wraps the HTML <cite> tag around the marked content.

      • Georg Makowski
    • Old reprint of a classic proof by Diophantus followed by Fermat’s famous last conjecture
      • Docs
      • ›
      • Improved
      • ›
      • Shortcodes

      Marginal Note

      A marginal note contains additional important but nonessential information. It explains some context, sheds light on a detail or speculates on a given topic etc.

      • Georg Makowski
    • Some HTML figure tags on a computer screen
      • Docs
      • ›
      • Improved
      • ›
      • Shortcodes

      Figure

      Because no Markdown element corresponds to the complex HTML <figure> tag, this shortcode was the solution for stand-alone images.

      • Georg Makowski
      • Docs
      • ›
      • Plugins

      LaTeX

      LaTeX is the most popular typesetting system for the natural sciences. The syntax has been established as a quasi-standard for complex mathematical formulas in print and web layouts.

      • Georg Makowski
    • A woman with a big mono-fin swimming in a pool
      • Docs
      • ›
      • Plugins

      Mermaid

      Mermaid is a popular Javascript library creating SVG diagrams from text and code descriptions.

      • Georg Makowski
    • Big diagram on the walls of a room
      • Docs
      • ›
      • Plugins

      Kroki

      Generate SVG diagrams with the Kroki service by writing textual diagram descriptions into Markdown code blocks.

      • Georg Makowski
    • Person configuring his car on a touchscreen
      • Docs
      • ›
      • Appendix
      • ›
      • Config

      markup.yaml

      Markdown configuration file in config/_default

      • Georg Makowski
    • A HTML tag
      • Docs
      • ›
      • Appendix

      replacements.html

      This template file from the module hugo-mod-replacements contains the regular expressions for all replacement codes.

      • Georg Makowski
    • Computer keyboard
      • Docs
      • ›
      • Appendix

      Example Punctuation Keymap

      Punctuation Keymap of the German Keyboard Layout for Ubuntu.

      • Georg Makowski
    • A splashing drop of water
      • Blog
      • •
      • Markdown
      Mar 27, 2023

      Stand-alone Image Layout

      This page demonstrates the layout for advanced stand-alone images.

      • Georg Makowski
    • Splashing ring of water
      • Blog
      • •
      • Markdown
      Mar 23, 2023

      Embedded image (float)

      This page demonstrates the layout for advanced embedded images.

      • Georg Makowski
    • Code on a screen
      • Blog
      • •
      • Markdown
      Nov 1, 2022

      Code Block Layout Demo

      On large screens, code blocks expand into the margins as long as possible and may include up to 160 characters in one line.

      • Georg Makowski
    • Lexicon entry
      • Blog
      • •
      • Markdown
      Aug 27, 2022

      Nested Definition List

      A definition list inside a blockquote with a sub-list in one of its items is an interesting problem for Markdown layout.

      • Georg Makowski
    • Old reprint of a classic proof by Diophantus followed by Fermat’s famous last conjecture
      • Blog
      • •
      • Markdown
      Jul 4, 2022

      The Beauty of Marginal Notes

      Marginal notes add further information elegantly and unobtrusively. We can add them with the shortcode mnote.

      • Georg Makowski

    All Taxonomies

      • Markdown(51)‍•
      • Getting started(7)‍•
      • Hugo(7)‍•
      • Design(5)‍•
      • External(5)‍•
      • Module(4)‍•
      • Overview(4)‍•
      • Theme(4)‍•
      • Page(2)‍•
      • Release(2)‍•
      • Resources(1)‍•
      • Tip(1)
      • Block(18)‍•
      • Image(12)‍•
      • Inline(10)‍•
      • Configuration(9)‍•
      • Replacement(8)‍•
      • Attribute(7)‍•
      • Fluid Responsive(5)‍•
      • List(5)‍•
      • Diagram(4)‍•
      • Hugo(4)‍•
      • Feature(3)‍•
      • Punctuation(3)‍•
      • Shortcode(3)‍•
      • Code(2)‍•
      • Latex(2)‍•
      • Linebreak(2)‍•
      • Marginal Note(2)‍•
      • Mermaid(2)‍•
      • Paragraph(2)‍•
      • Quote(2)‍•
      • Search(2)‍•
      • Security(2)‍•
      • Accessible(1)‍•
      • Author(1)‍•
      • Color(1)‍•
      • Embedded(1)‍•
      • Favicon(1)‍•
      • File(1)‍•
      • Headings(1)‍•
      • License(1)‍•
      • Menu(1)‍•
      • Module(1)‍•
      • Parameter(1)‍•
      • Privacy(1)‍•
      • Related(1)‍•
      • Spacing(1)‍•
      • Table(1)‍•
      • Title(1)‍•
      • Tracking(1)‍•
      • VSCode(1)
      • Images(6)‍•
      • Demo(4)

    Theme

    Perplex logo

    Apache 2.0 license

    Credits

    Thanks to you all!

    Content

    unless noted otherwise.

    Generated with

    Hugo logo

    Apache 2.0 license

    Deployed with

    Netlify logo

    and

    Tested with

    HTML-Proofer, Sonarcloud, Wave and

    Browserstack logo

    Legal matters

    • Licenses
    • Impressum (German)