In this article, you will learn how YAML compares to XML and JSON - two languages also used for creating configuration files.

You will also learn some of the rules and features of the language, along with its basic syntax.

Here is what we will cover:

1. What is YAML?
2. XML VS JSON VS YAML - What's The Difference?
   1. XML
   2. JSON
   3. YAML
3. Features and basic rules of YAML
   1. How to create a YAML file
   2. Multi-document support in YAML
   3. Indentation in YAML
   4. Tabs in YAML
   5. Whitespace in YAML
   6. Explicit data types in YAML
4. An introduction to YAML syntax
   1. Scalars
   2. Collections

What is YAML?

YAML stands for YAML Ain't Markup Language, but it originally stood for Yet Another Markup Language.

YAML is a human-readable data serialization language, just like XML and JSON.

Serialization is a process where one application or service that has different data structures and is written in a different set of technologies can transfer data to another application using a standard format.

In other words, serialization is about translating, converting, and wrapping up a data structure in another format.

The data in the new format can be stored in a file or transmitted to another application or service over a network.

YAML is a widely used format for writing configuration files for different DevOps tools, programs, and applications because of its human-readable and intuitive syntax.

XML VS JSON VS YAML - What's The Difference?

XML, JSON, and YAML are all used for creating configuration files and transferring data between applications.

Each language has its advantages and disadvantages.

Now, let's see some of the characteristics of the three languages. You will also see an example of how the same code is written in each language to demonstrate the high-level differences in their syntax.

XML

XML, which stands for Extensible Markup Language, was first introduced in 1996 and was designed for general-purpose use.

XML is a generalized markup language. It offers a structured yet flexible syntax and a defined document schema. This makes it a good choice when working with complex configurations that require a structured format and finer control over schema validation to ensure configurations always have the correct format.

With that said, XML's syntax can be verbose, redundant, and harder to read in comparison with other serialization languages.

<Employees>
    <Employee> 
        <name> John Doe </name>
        <department> Engineering </department>
        <country> USA </country>
    </Employee>
     <Employee> 
        <name> Kate Kateson </name>
        <department> IT Support </department>
        <country> United Kingdom </country>
    </Employee>
</Employees>

JSON

JSON stands for JavaScript Object Notation and has been around since the early 2000s.

JSON was initially inspired by the JavaScript programming language, but it is not tied to only one language. Instead, it is a language-independent format.

Most modern programming languages have libraries for parsing and generating JSON data.

JSON offers a much more readable, human-friendly, compact, and simple syntax compared to XML. It makes for a great format for storing and transferring information between web applications and servers over a network.

With that said, it may not offer the best support for complex configurations.

{
    "Employees": [
    {
            "name": "John Doe",
            "department": "Engineering",
            "country": "USA"
        },

        {
            "name": "Kate Kateson",
            "department": "IT support",
            "country": "United Kingdom"
        }
    ]
}

YAML

YAML, originally known as Yet Another Markup Language, was created in 2001 but now stands for YAML Ain't Markup Language.

YAML is an official strict superset of JSON despite looking very different from JSON.

YAML can do everything that JSON can and more. A valid YAML file can contain JSON, and JSON can transform into YAML.

YAML has the most human-readable, intuitive, and compact syntax for defining configurations compared to XML and JSON.

YAML uses indentation to define structure in the file, which is helpful if you are used to writing Python code and are familiar with the indentation style the language uses.

With that said, if you don't get the indentation and format right, it can lead to validation errors, making it not the friendliest for beginners.

Employees:
- name: John Doe
  department: Engineering
  country: USA
- name: Kate Kateson
  department: IT support
  country: United Kingdom

Features and Basic Rules of YAML

Now, let's go over some of the basic rules and features of the language.

How to Create a YAML File

To create a YAML file, use either the .yaml or .yml file extension.

Multi-Document Support in YAML

Before writing any YAML code, you can add three dashes (---) at the start of the file:

---
Employees:
- name: John Doe
  department: Engineering
  country: USA
- name: Kate Kateson
  department: IT support
  country: United Kingdom

YAML allows you to have multiple YAML documents in a singe YAML file, making file organization much easier.

Separate each document with three dashes (---):

---
Employees:
- name: John Doe
  department: Engineering
  country: USA
- name: Kate Kateson
  department: IT support
  country: United Kingdom
---
Fruit:
 - Oranges
 - Pears
 - Apples

You can also use three dots (...) to mark the end of the document:

---
Employees:
- name: John Doe
  department: Engineering
  country: USA
- name: Kate Kateson
  department: IT support
  country: United Kingdom
...

Indentation in YAML

In YAML, there is an emphasis on indentation and line separation to denote levels and structure in data. The indentation system is quite similar to the one Python uses.

YAML doesn't use symbols such as curly braces, square brackets, or opening or closing tags - just indentation.

Tabs in YAML

YAML doesn't allow you to use any tabs when creating indentation - use spaces instead.

Whitespace in YAML

Whitespace doesn't matter as long as child elements are indented inside the parent element.

How to Write A Comment in YAML

To add a comment to comment out a line of code, use the # character:

---
# Employees in my company
Employees:
- name: John Doe
  department: Engineering
  country: USA
- name: Kate Kateson
  department: IT support
  country: United Kingdom

Explicit Data Types in YAML

Although YAML auto-detects the data types in a file, you can specify the type of data you want to use.

To explicitly specify the type of data, use the !! symbol and the name of the data type before the value:

# parse this value as a string
date: !!str 2022-11-11

## parse this value as a float (it will be 1.0 instead of 1)
fave_number: !!float 1

An Introduction to YAML Syntax

Scalars

Scalars in YAML are the data on the page - strings, numbers, booleans, and nulls.

Let's see some examples of how to use each one.

In YAML, strings in some cases can be left unquoted, but you can also wrap them in single (' ') or double (" ") quotation marks:

A string in YAML!

'A string in YAML!'

"A string in YAML!"

If you want to write a string that spans across multiple lines and you want to preserve the line breaks, use the pipe symbol (|):

|
 I am message that spans multiple lines
 I go on and on across lines
 and lines
 and more lines

Make sure that the message is indented!

Alternatively, if you have a string in a YAML file that spans across multiple lines for readability, but you want the parser to interpret it as a single line string, you can use the > character, which will replace each line break with a space:

>
 I am message that spans
 multiple lines
 but I will be parsed
 on one line

Again, make sure you don't forget to indent the message!

Numbers express numerical data, and in YAML, these include integers (whole numbers), floats (numbers with a decimal point), exponentials, octals, and hexadecimals:

# integer
19

# float 
8.7

# exponential
4.5e+13

# octal 
0o23

# hexadecimal
0xFF

Booleans in YAML, and other programming languages, have one of two states and are expressed with either true or false.

Words like true and false are keywords in YAML, so don't surround them with quotation marks if you want them interpreted as booleans.

Lastly, Null values are expressed with the keyword null or the tilde character, ~.

Collections

More often than not, you will not be writing simple scalars in your YAML files - you will be using collections instead.

Collections in YAML can be:

• Sequences (lists/arrays)
• Mappings (dictionaries/hashes)

To write a sequence, use a dash (-) followed by a space:

- HTML
- CSS
- JavaScript

Each item in the sequence (list) is placed on a separate line, with a dash in front of the value.

And each item in the list is on the same level.

That said, you can create a nested sequence (remember, use spaces - not tabs - to create the levels of indentation):

- HTML
- CSS
- JavaScript
 - React
 - Angular
 - Vue

In the sequence above, React, Angular and Vue are sub-items of the item JavaScript.

Mappings allow you to list keys with values. Key/value pairs are the building blocks of YAML documents.

Use a colon (:) followed by a space to create key/value pairs:

Employees:
 name: John Doe
 age: 23
 country: USA

In the example above, a name gets assigned to a specific value.

The value John Doe gets mapped (or assigned) to the name key, the value 23 gets mapped to the age key, and the value USA gets mapped to the country key. Altogether, these create an object.

You can also use a mapping with a sequence.

For example, taking the example sequence from earlier on, here is how you would build a list of frontend_languages:

frontend_languages:
 - HTML
 - CSS
 - JavaScript
  - React
  - Angular
  - Vue

In the example above, I created a list of frontend_languages, where there are multiple values under the same key, frontend_languages.

Similarly, you can create a list of objects:

Employees:
- name: John Doe
  department: Engineering
  country: USA
- name: Kate Kateson
  department: IT support
  country: United Kingdom

Conclusion

Hopefully, this article was helpful and gave you insight into what YAML is, what the syntax of the language looks like, and how it differs from XML and JSON.

Thank you for reading, and happy coding!

Jamstack takes advantage of existing technologies – which we'll discuss in a minute. The result is better performance, improved security, and easier scalability for web applications.

In this article, you'll learn what Jamstack means and the benefits of using this approach in your projects.

What is the Jamstack?

Jamstack is a web development architecture. Matt Biilmann, the CEO of Netlify, popularized it with his presentation at Smashing Conference 2016.

Jamstack is an acronym for Javascript, APIs, and Markup, and is a technology stack you use to build your apps.

This is like the MERN stack (MongoDB, ExpressJS, ReactJS and NodeJS) and the MEAN stack (MongoDB, ExpressJS, Angular and NodeJS) – just with different tools.

Now let's discuss the various components of a Jamstack web application:

Javascript

Javascript is the core programming language of the web. It has been around for decades and you can use it both on the client side and the backend with NodeJS.

Javascript is the programming language you use for handling the client side of your Jamstack applications.

APIs

API is an acronym for Application Programming Interface. It's an interface which helps two or more computer programs communicate with each other.

In Jamstack apps, you use APIs to communicate with your backend.

Markup

Markup refers to standard text-encoding systems consisting of a set of symbols inserted into a text document. Examples of markup languages are HTML, XML, and templating languages such as JSX.

In the Jamstack, markup refers to the content of a Jamstack application. Note that we use markup here in its broader sense. It doesn't refer to text content only but also to the assets of the web application, such as images.

Important Features of Jamstack Apps

To consider an application a Jamstack app, it should meet the following conditions:

Distributed Architecture

This refers to the decoupling of the client side from the backend. The client side handles the presentation of the user interface, and the backend handles business logic and data.

Communication between the frontend and backend happens via a dedicated API. This means that a change or upgrade in one will not affect the other. This results in easier maintenance of the entire web application.

Static Sites

It is important for Jamstack applications to serve static web pages and not dynamic ones.

Traditional web applications are dynamic sites. This means that when you request a page, the backend will have to reach a database to retrieve the data. The data is then used to generate HTML files, and then sent back to the client.

The disadvantage of dynamic sites is how long it takes to complete these steps.

For static sites, the pages are already pre-rendered at build time. So every time you request a page, you get the pre-rendered page.

This eliminates the time that dynamic sites spend in obtaining data, generating HTML files, and sending it back to the client. You can serve your static sites from a content delivery network (CDN). This will lead to improved speed and reduced costs.

Examples of static site generators that you can use for your Jamstack web applications include:

• NextJS

• Gatsby

• Hugo

• Jekyll

• Nuxt

Why Should You Use the Jamstack for your Web Applications?

Let's now discuss some of the reasons the Jamstack web architecture has become so popular in recent times and why you should consider adopting it:

Jamstack Apps Are Scalable

You can serve most Jamstack applications from a CDN. This allows for the speedy transfer of assets needed for loading web pages.

As a result of the distributed nature of CDNs, your web application will also be able to handle more traffic at a reduced cost.

Jamstack Apps Are Easy to Maintain

Jamstack applications are easier to maintain since their client side is decoupled from their backends.

This means that you can maintain one part without requiring major modifications to the other.

Jamstack Apps Load Faster

As stated earlier, serving your site from a CDN increases the speed with which it loads.

Also, in Jamstack applications, web pages are prebuilt, saving time that would normally be spent retrieving and generating HTML files every time you make a request.

Jamstack Apps Are Cheaper

Since Jamstack applications are easier to maintain and deploy, they are cheaper compared to their traditional counterparts.

Jamstack Apps Are More Secure

Since you do not have to constantly maintain a server in Jamstack applications and the pages are constructed on read-only files (that is, the pages are static), you can worry less about the security of your applications.

Conclusion

Despite the fact that more and more projects are being built using the Jamstack architecture, we're still in the relatively early stages of its adoption.

I believe that more large and small businesses will adopt it in the near future in place of costly monolithic architectures.

An XML file contains tags that specify how the document should be structured and how it should be stored and transmitted over the internet.

It is no longer the preferred method for organizing and transmitting data, but many legacy systems still use it. Also, both RSS and SVG are based on the XML format.

This is how XML appears:

<?xml version="1.0" encoding="UTF-8"?>
<catalog>
   <book id="bk1">
      <author>Corets, Eva</author>
      <title>Maeve Ascendant</title>
      <genre>Fantasy</genre>
      <price>5.95</price>
   </book>
   <book id="bk2">
      <author>Corets, Eva</author>
      <title>Oberon's Legacy</title>
      <genre>Fantasy</genre>
      <price>5.95</price>
   </book>
   <book id="bk3">
      <author>Corets, Eva</author>
      <title>The Sundered Grail</title>
      <genre>Fantasy</genre>
      <price>5.95</price>
   </book>
</catalog>

In this article, you will learn the various ways you can open an XML file, either on your computer or online.

How to Open an XML File Using a Text Editor

You must have an XML file you are trying to open, either to view only or to view and edit.

If you want to open an XML file and edit it, you can use a text editor. You can use default text editors, which come with your computer, like Notepad on Windows or TextEdit on Mac.

All you have to do is locate the XML file, right-click the XML file, and select the "Open With" option. This will display a list of programs to open the file.

Select Notepad if it is a Windows computer or TextEdit if it is a Mac computer, as shown in the image above. These two are pre-installed text editors for each operating system and should already be on the list. Any basic text editor will work.

You can use other text editors like VSCode (which is suggested on the image above), Atom, Sublime Text and others. But it is always best to use default editors for basic tasks like this, as text editors like VSCode, Atom, and Sublime Text are pretty heavy programs.

How to Open an XML File Using a Browser

If you only want to view the file, you can use any web browser such as Safari, Chrome, and lots more with similar procedures.

The first step is to locate the XML file you want to open, right-click the file, and select the “open with” option. A list of options will appear, including some browsers.

Click on your preferred browser, and then your XML will load up.

Another option would be to open your browser and then drag the XML file to the browser. This also works for text editors.

How to Open an XML File Online

On the internet, dozens of XML viewers and even converters help convert XML files to other formats like JSON. Here are some of the most popular online XML viewers/editors:

• Code Beautify

• JSON Formatter

• Tutorialspoint

• JSON Formatter

• Google Chrome Extension

Each one works similarly, allowing you to upload the XML file from your computer.

Chrome has an XML Viewer extension, which works like all these online XML viewers. All you have to do is download the extension. Then click on it whenever you want to open an XML file.

Once you click on it, an interface that is easy to navigate will appear with two major options you can use to upload your XML file: From your PC or From your Google Drive.

When you select an option, you can search for the file, and within a few milliseconds, your XML file will open in the plain section.

Ta-da 😂

In this short article, you have learned how to open an XML file. I hope this will help you.

Have fun coding!

And you may know that HTML is a language used to create websites – but what does markup mean?

Markup languages are languages that use tags to define different elements within a text document. Most people are familiar with Rich Text Editors – programs that allow users to add extra formatting, images, and links to their documents.

A screenshot of the GUI of the Microsoft Word software (a Rich Text Editor).

But markup languages use tags like:

• is a paragraph tag.

• makes bold text.

There are quite a few markup languages like XML, HTML, and the topic of this article: Markdown.

Developers generally use markdown for documentation – and it is often included in most repositories. For example, I used markdown to write this article on freeCodeCamp.

So let's look at all we can do with markdown.

Disclaimer: There is no unifying body or specification to standardise markdown – just some widely accepted best practices. So your mileage might vary depending on what markdown parser you're using for this cheat sheet.

Markdown Cheat Sheet

Here are some of the most commonly used methods for manipulating text in markdown.

How to Create Headers in Markdown

There are six markdown headers, H1 thorough to H6. I'll show you how it displays visually, and also the way you create it using markdown.

H1's are the biggest and generally are the "main" headers, and each header after H1 gets smaller.

H1 tag

# H1 tag

H2 tag

## H2 tag

H3 tag

### H3 tag

H4 tag

#### H4 tag

H5 Tag

##### H5 tag

H6 tag

###### H6 tag

How to Add Typographical Emphasis in Markdown

The ways you commonly add emphasis with text are bold, italics and strikethroughs. Combining too much emphasis can make words much less clear, so choose carefully how you want to emphasize each bit of text.

There are also subscript and superscript notation that you'll use to write the names of various chemical compounds, for example. You may also use them as part of mathematical notation.

How to make text bold:

Add double asterisks around your text. It'll make that text appear bold. Like this: **Bold text**

How to make your text italic:

Add single asterisks around your text to make it appear in italics, like this: *Italics*

How to Strike through certain text:

If you want to "cross something out" in text, use the strikethrough method, like this: ~~Strike through~~.

How to Write Subscripts in Markdown

If you want to write the chemical symbol for water, for example, you can make a subscript "2" by typing H~2~0.

This results in: H₂0.

How to Write Superscripts in Markdown

Say you want to write an exponent - or superscript. You do that like this: X^2^ which results in this: X².

How to Make Lists in Markdown

There are multiple types of lists in markdown. For example, you can have ordered lists and unordered lists.

Ordered lists are commonly used when you want to follow steps in a certain order (like following a recipe: cook the chicken...serve the dish). But unordered lists work well for things that don't require sequential steps like a recipe (a shopping list, for example).

How to Make an Unordered List in Markdown

This is how the unordered list looks.

• Chili oil

• Rice

• Spring onions

And this is how you create it in markdown:

- Chili oil
- Rice
- Spring onions

How to Make an Ordered List in Markdown

This is how the ordered list looks.

1. First item

2. Second item

And this is how you create it in markdown:

1. First item 
2. Second item

How to Create Links in Markdown

The two most common ways of linking things in markdown documents is either by hyperlinks or images. Both can help make your writing much clearer and more eloquent, and should be used where appropriate.

Here's what a hyperlink in text looks like:

Kealan's site

And here's how you'd create that link in Markdown:

[Kealan's site](https://www.kealanparr.com)

You put the text you want to link in square brackets (here, "Kealan's site"), and then immediately follow them with parenthesis containing the URL.

Say you want to include an image in an article. To get it to appear like this:

You simple use the following notation:

![View of natural rock landscape formations making a valley ending in a road crossing through with a blue sky.](https://images.unsplash.com/photo-1660866838784-6c5158c0f979?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=387&q=80)

It's similar to a regular link, but you include the exclamation point before the brackets.

How to Use HTML in Markdown

You can use regular HTML in Markdown documents (depending on the parser that's being used).

So feel free to just input any valid HTML you like.

How to Add Spacing in Markdown

If you want to add a horizontal line to divide up sections of a document, you can make one like this:

By using three dashes like this:

---

How to Create Tables in Markdown

Tables come in handy in your articles. To make a table that looks like this:

Here's the notation you'd use:

| Name   | Age |
| ------ | --- |
| Kealan | 25  |
| Jake   | 28  |

The only real "gotcha" you have to be aware of when making a markdown table is that you keep the pipes (|) vertically in line. Then your markdown table will appear as above in this article. An image to make that clearer is:

A markdown table is displayed, with Name and Age as the headers and Kealan, Jake and 25 & 28 as the values.

How to Add Code and Syntax in Markdown

Adding code snippets to your markdown can be incredibly helpful if you are creating documentation for developers, for example.

The below is a very simple JavaScript example, but almost all modern programming languages are supported (with syntax highlighting and so on).

console.log('example log')

console.log('example log')

Just type the three backticks followed by the programming language and then enter to start writing your code. End the code block with three backticks.

How to Add Quotes in Markdown

When you reference someone else's work, it is expected and courteous to credit them. One easy way you can do that is by quoting them.

If you want to add quotes in markdown:

"This is a quote, from someone who is very wise" - Anonymous

Just add this symbol, which renders it like the above quote:

> "This is a quote, from someone who is very wise" - Anonymous

Conclusion

I hope this has been a useful reference for you, and that you've learned a new feature of markdown you hadn't seen before.

There are lots more features (not even counting all the HTML variations you could create), but this article has covered the most used features.

It is one of the most basic building blocks of every website, so it's crucial to learn if you want to have a career in web development.

In this article, I will walk you through what HTML is about in detail, how it does things on web pages, and we'll also touch on a really cool part of HTML – Semantic HTML.

What is HTML?

To understand "HTML" from front to back, let's look at each word that makes up the abbreviation:

Hypertext: text (often with embeds such as images, too) that is organized in order to connect related items

Markup: a style guide for typesetting anything to be printed in hardcopy or soft copy format

Language: a language that a computer system understands and uses to interpret commands.

HTML determines the structure of web pages. This structure alone is not enough to make a web page look good and interactive. So you'll use assisted technologies such as CSS and JavaScript to make your HTML beautiful and add interactivity, respectively.

In this case, I like to break down the three technologies – HTML, CSS, and JavaScript – this way: they are like a human body.

• HTML is the skeleton,
• CSS is the skin,
• and JavaScript is the circulatory, digestive, and respiratory systems that brings the structure and the skin to life.

You can also look at HTML, CSS, and JavaScript this way: HTML is the structure of a house, CSS is the interior and exterior decor, and JavaScript is the electricity, water system, and many other functional features that make the house livable.

HTML Tags

Since HTML defines the markup for a particular web page, you'll want the text, images, or other embeds to appear in certain ways.

For example, you might want some text to be big, other text to be small, and some to be bold, italic, or in bullet point form.

HTML has "tags" that let you get this done. So, there are tags to create headings, paragraphs, bolded words, italicized words, and more.

The image below describes the anatomy of an HTML tag:

HTML Elements

An element consists of the opening tag, a character, the content, and a closing tag. Some elements are empty – that is, they don't have a closing tag but instead have a source or link to content that you want to embed on the web page.

An example of an empty element is <img>, which you use to embed images on a web page.

HTML elements are often used interchangeably with tags, but there's a small difference between the two. An element is a combination of the opening and closing tag, and then the content between them.

I made another image to help you visualize the anatomy of an HTML element:

HTML Attributes

HTML tags also take what are called attributes. These attributes are placed in the opening tag and range from style and ids to classes. They take values, which convey more information about the element and help you do things such as styling and manipulation with JavaScript.

In the infographic below, the opening tag contains a class attribute with a value of “text”. This can be used to style the element or select it with JavaScript for interactivity.

Here's the anatomy of a basic HTML page:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Definition of HTML</title>
  </head>
  <body>
    <!--Page content such as text and images goes in here-->
  </body>
</html>

Let's look at the important bits of code here:

<!Doctype html>: Specifies that we're using HTML5 in this code. Before the introduction of HTML5, you had to explicitly state which version of HTML you were coding in with the <!Doctype> tag. For example, HTML4.0, 3.2, and so on. But now we no longer need it. When “html” is written in the code, the browser automatically assumes that you are coding in HTML5.

<html></html>: the root, or top-level element of every HTML document. Every other element must be wrapped in it.

<head></head>: one of the most crucial parts of the HTML document. Web crawlers look inside the head tags to get important information about the page. It contains info such as the page title, stylesheets, meta information for SEO, and lots more.

<meta />: this is an empty element that conveys meta-information about the page. Such information may include the author, what type of encoding it's using (almost always UTF-8), responsiveness, compatibility, and a lot more. Web crawlers always look at the meta tag to get information about the web page, which will play a crucial role in SEO.

<title></title>: this defines the title of the web page. It is always shown in the browser tab.

<body></body>: all the content of the HTML document is located inside the body tag. There can only be one <body> tag on the whole page.

What is Semantic HTML?

Semantic HTML means that your HTML tags convey the actual meaning of what they are used for.

Semantics has been an integral part of HTML since its inception in the early 90s. But it never gained particular relevance until the late 90s when CSS started working in most browsers.

With semantic HTML, semantically-neutral tags such as <div> and <span> are frowned upon since semantically more descriptive tags such as <header>, <nav>, <main>, <section>, <footer> and <article> can do the same thing they do.

A noticeable advantage of using semantic tags is that web crawlers are able to index the web page or website easily, improving SEO in return.

In addition, a website that uses semantics becomes more informative, adaptable, and accessible to those who use screen readers to access websites.

Important Semantic Tags and What they Do

Let's look at some of the most commonly used semantic HTML tags:

<header>: The <header> element defines the introductory section of a web page. It contains items such as the logo, navigation, theme switcher, and search bar.

<nav>: The <nav> element specifies the navigation items of the page such as home, contact, about, FAQs, and so on.

<main>: The <main> element is conventionally treated as the immediate descendant of the tag. It contains the main sections of the HTML document apart from <header> and <footer>. Ideally, there should be just one of these in the whole HTML document.

<section>: The <section> element defines a particular section of the web page. This may be the showcase section, about section, contact section, or others. You can use numerous sections in a single HTML document.

<article>: The <article> element represents a certain part of a web page that conveys some particular information. Such information could be a combination of text, images, videos, and embeds. Look at this element as a standalone blog post on a page containing excerpts about other blog posts.

<aside>: As the name implies, this represents a sidebar on a web page. It is usually a part of the web page that is not directly related to the main content.

<footer>: The <footer> element accommodates items such as quick links, copyright information, or any other data related to the entire website or web page.

Note that since semantic elements convey actual meaning and what some particular content actually does (such as nav for navigation, aside for a sidebar, and so on), these elements are not automatically positioned where they are supposed to be. You still have to do that with CSS.

A super simple semantic HTML document looks like this:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Definition of HTML</title>
  </head>

  <body>
    <header>
      <h1 class="logo">LOGO</h1>
      <nav>
        <ul>
          <li>Home</li>
          <li>About</li>
          <li>Contact</li>
          <li>FAQs</li>
        </ul>
      </nav>
    </header>
    <main>
      <section class="about-me">
        <article>
          Lorem ipsum dolor, sit amet consectetur adipisicing elit. Optio magni
          est asperiores nemo, adipisci minus itaque quam, rem libero aliquam
          nesciunt, nisi inventore assumenda earum repellat labore ratione
          architecto eos quis. Soluta mollitia cupiditate dolorem. Consequatur a
          soluta laudantium nihil. Molestias, officiis ut! Nobis adipisci
          voluptatem quam at officia beatae!
        </article>
      </section>
      <section class="contact-me">
        You can find me on
        <a href="https://twitter.com/koladechris">Twitter</a> You can find me on
        <a href="https://Instagram.com/koladechris">Instagram</a>
      </section>
      <aside class="address">My Address</aside>
    </main>
    <footer>© 2020 All Rights Reserved</footer>
  </body>
</html>

Here's what it looks like in the browser:

You can see that the content inside the <aside> tag isn't in the sidebar and the content inside the <nav> tag is not automatically available as the navigation bar. This is why you still have to make them look the way they are supposed to look with CSS.

Conclusion

I hope this article has helped you learn the basics of HTML and what it does. Now you can start to learn more advanced technologies such as CSS and JavaScript, and then start forming a solid career in web development.

Thanks a lot for reading and have a nice time.

XML was designed to simplify data sharing and data transport, and focuses on structuring that information in a logical way.

Syntax of XML

The syntax for XML is very straight forward and quite easy to learn.

XML documents must contain one root element that is the parent of all other elements:

<root>
  <child>
    <subchild>.....</subchild>
  </child>
</root>

Above syntax shows the root element which is necessary while creating an XML code.

But the root element can be called anything. For example:

<?xml version="1.0" encoding="UTF-8"?>
<note>
  <to>Tove</to>
  <from>Jani</from>
  <heading>Reminder</heading>
  <body>Don't forget me this weekend!</body>
</note>

In the code above <note> is the root element.

Advantages of using XML:

• Simplicity - XML documents are ordinary text files that can be created and edited with any text editor.
• Vendor independence
• Platform independence
• Extensive infrastructure

Disadvantages of using XML:

• Verbose and cumbersome syntax
• Highly inefficient storage

Introduction: What’s the Problem?

There are many document markup languages available already. Wikipedia lists over 70 variations in its List of document markup languages — among them HTML, Markdown, Docbook, Asciidoctor, reStructuredText, etc.

Why, then, does the title of this article suggest we need yet another one???

What’s the problem?

There are two fundamental problems with the existing document markup languages: Either they are not easy to use, or they are not well suited to write complex documents, such as technical articles, user manuals, or books. An example of “not easy to use, but suited for complex documents” would be Docbook. An example of “easy to use, but not suited for complex documents” would be Markdown.

Of course, the above categorization is simplistic. But it should serve as a good starting point to get the gist of this article which aims to delineate the kind of problems that occur in practice. You’ll see many representative examples of markup code that illustrates what’s wrong, complemented by links to more information.

You’ll also discover a new markup language. Lots of examples will demonstrate how a new syntax can lead to a language that is “easy to use and suited for complex documents”. A proof-of-concept implementation is already available. More on this later.

Preliminary Remarks

Please note:

• This article is about document markup languages used to write text documents, such as books and articles published on the net. There are other markup languages used to describe specific data, such as mathematical formulas, images, and geographic information, but these are out of scope of this article. However, some ideas presented in this article might be applied to other kinds of markup languages as well.
• This article focuses solely on the syntax of markup languages. We will not discuss other aspects that are also important in the choice of a suitable markup language, such as: support on your OS, ease of installation and dependencies, the tool chain available to create final documents, the quality of documentation, price, customer/user support, etc.
• Readers of this article should have some basic experience with a markup language like HTML, Markdown, Asciidoctor, or similar.
• Readers not aware of the many advantages of document markup languages might first want to read:
  Advantages of Document Markup Languages vs WYSIWYG Editors (Word Processors)

Inconveniences / Part 1

Let us first consider some well-known markup languages and have a look at some inconveniences.

HTML

HTML is the language of the web. So, why not write everything in HTML? The reasons to discard this option are well known. Let’s quickly recapitulate them.

HTML is cumbersome to write. Nobody wants to write XML code by hand, although editors with HTML/XML support might help.

Some frequent writing tasks require non-trivial HTML code.

Suppose we want to display a horizontally centered image with a simple black border and a link. The HTML code an inexperienced user would expect to work could look like this:

<img src="ball.png" align="center" border="yes" link="http://www.example.com/ball">

But the code he or she actually has to write is cumbersome and there are different ways to do it. Here is one way:

<div style="text-align: center">
    <a href="http://www.example.com/ball">
        <img src="ball.png" style="border:1px solid black;">
    </a>
</div>

HTML lacks “productivity features for writers”, such as:

• Automatic generation of a table of contents, index, glossary, etc.
• Variables used to hold recurring values
• Splitting a document into different files

Other inconveniences will be shown later.

Markdown

Markdown is a very popular, lightweight markup language. It is easy to learn and use, and well suited for short and simple texts, such as comments in forums, readme files, etc.

However, it suffers from the following problems that make it unsuitable for complex or big documents (e.g. technical articles, user manuals, and books):

• The original Markdown defined by John Gruber lacks many features expected by writers, such as tables (only embedded HTML tables are supported), automatic generation of table of contents, syntax highlighting, file splitting, etc.
• There is no unique, unambiguous specification for Markdown. Many flavors of Markdown exist, with different rules and different features supported. This leads to incompatibility issues when markup code is shared. CommonMark is an attempt to solve this problem. However, the specification is huge and not completed yet (at the time of writing, April 2019, version 0.28, dated 2017–08–01, is the latest one).
• Markdown has similar problems and limitations to those shown later in chapter “Inconveniences / Part 2”. These flaws can quickly become an annoyance when you use Markdown for anything else than short, simple texts.

Here is a list of articles with more information about Markdown’s shortcomings:

• Why You Shouldn’t Use “Markdown” for Documentation
• Sundown on Markdown?
• Why Markdown Is Not My Favourite Language

Docbook

Docbook is an XML-based markup language that uses semantic tags to describe documents.

It has probably the most complete set of features among all markup languages. It has been used by many authors, is pre-installed on some Linux distributions, and is supported by many organizations and publishers. Docbook has been successfully used to create, publish, and print lots of big documents of all kinds.

But it has the following drawbacks:

It uses XML and a verbose syntax. Look at the following example, borrowed from Wikipedia:

<?xml version="1.0" encoding="UTF-8"?>
<book xml:id="simple_book" xmlns="http://docbook.org/ns/docbook" version="5.0">
    <title>Very simple book</title>
    <chapter xml:id="chapter_1">
        <title>Chapter 1</title>
        <para>Hello world!</para>
        <para>I hope that your day is proceeding <emphasis>splendidly</emphasis>!</para>
    </chapter>
    <chapter xml:id="chapter_2">
        <title>Chapter 2</title>
        <para>Hello again, world!</para>
    </chapter>
</book>

Would you enjoy writing and maintaining such code?

Now compare the above code with the following one, written in a modern markup language like Asciidoctor:

= Very simple book

== Chapter 1

Hello world!

I hope that your day is proceeding _splendidly_!

== Chapter 2

Hello again, world!

Docbook is also complex, and therefore hard to learn and use.

Output produced by Docbook, especially HTML, looks old-fashioned (see examples on its website). Of course, presentation can be customized, but this is not an easy task.

LaTeX

LaTeX is a high-quality typesetting system. It is widely used in academia to create scientific documents. It is considered to be the best option for writing PDF documents containing lots of mathematic formulas and equations.

I never used LaTeX myself, because I don’t write scientific documents — just articles and books to be published on the web. Therefore, I don’t want to comment on it too much. However, it is important to mention it because of its popularity in academia.

LaTeX’s unique syntax seems verbose to me, and a bit complex. Here is an abbreviated example from Wikipedia:

\documentclass{article}
\usepackage{amsmath}
\title{\LaTeX}

\begin{document}
    \maketitle
    \LaTeX{} is a document preparation system ...

    % This is a comment
    \begin{align}
        E_0 &= mc^2 \\
        E &= \frac{mc^2}{\sqrt{1-\frac{v^2}{c^2}}}
    \end{align}  
\end{document}

The article Conversion from (La)TeX to HTML states that converting LaTeX math to HTML is “a challenge”.

Some markup languages allow LaTeX snippets to be embedded in their markup code, which can be very useful if you need the power of LaTeX for maths. There are other options to display maths on the web, such as Mathjax or MathML (an ISO standard and part of HTML5).

Popular for Big Documents

A impressive number of markup languages have emerged. Many of them use a syntax similar to Markup, and are therefore easy to learn and use. Some have more features than Markdown and are even extensible. However, as soon as we start writing complex documents, corner-cases and limits diminish the initial joy of using them.

Two popular markup languages used for big documents are Asciidoctor (an improved version of Asciidoc), and reStructuredText (an improved version of StructuredText). We will have a look at them soon.

Practical Markup Language (PML)

Before moving on to the most interesting part of this article, let me briefly introduce the new markup language I mentioned already in the introduction.

The language is called Practical Markup Language (PML).

“fitting the needs of a particular situation in a helpful way; helping to solve a problem or difficulty; effective or suitable”

— definition of ‘practical’ in the Cambridge Dictionary

I started the PML project a few months ago because I couldn’t find a markup language that was easy to use and well suited for big, complex documents, such as a user manual.

In the next section we’ll look at examples of markup code written in PML, compared to code written in other languages. So let’s first mention two basic PML syntax rules needed to understand the upcoming examples.

A PML document is a tree of nodes (similar to an XML/XHTML document). Each node starts with a {, followed by a tag name. Each node ends with a }. A node can contain text or child nodes.

For example, here is a node containing text that will be rendered in italics:

{i bright}

This node starts with {i , and ends with }. i is the tag name. In this case i is an abbreviation for italic, which means that the node's content will be rendered in italics. The content of this node is the text bright. The above PML markup code will be rendered as:
bright

Some nodes have attributes, used to specify additional properties of the node (besides its tag name).

For example, the title of a chapter is defined with attribute title, as follows:

{chapter title=A Nice Surprise
    Once upon a time ...
}

There is not much more to say about the basic concept of PML syntax. For more insight, and a description of features not used in this article, please consult the PML User Manual.

You can download and play around with a free implementation of PML. But please note: PML is a work in progress. There are missing features, you might encounter bugs, and backwards compatibility is currently not guaranteed.

I use PML myself to write all my web documents, such as this article. For links to more real-life examples please visit the FAQ.

Inconveniences / Part 2

I this section we’ll look at examples that reveal some problems encountered with markup languages. This is by no means an exhaustive enumeration of all troubles and corner cases. The aim is to just show a few examples that demonstrate the kind of inconveniences and limits encountered in the real world.

For each example the markup code will be shown in HTML, Asciidoctor, reStructuredText, and PML.

If you want to try out some code, you can use the following online testers (no need to install anything on your PC):

• HTML
• Asciidoctor
• reStructuredText

An online tester for PML is not yet available. You have to install PML on a Windows PC if you want to try it out.

Font Styles

Font styles (italic, bold, monospace, etc.) are often used in all kinds of documents, so good support is essential.

But as we will see, surprises and limits can emerge, as soon as we have to deal with non-trivial cases. Let’s look at some examples to illustrate this.

Part of a Sentence in Italics

Suppose we want to write:
They called it Harmonic States, a good name.

This is a trivial case, and all languages support it.

HTML:

They called it <i>Harmonic States</i>, a good name.

Asciidoctor:

They called it _Harmonic States_, a good name.

reStructuredText:

They called it *Harmonic States*, a good name.

PML:

They called it {i Harmonic States}, a good name.

Part of a Word in Italics

We want to write:
She _un_wrapped the challenge first.

HTML:

She <i>un</i>wrapped the challenge first.

Asciidoctor:

She __un__wrapped the challenge first.

Note that we have to use two underscores. Using a single underscore (as in the first example), would result in:
She _un_wrapped the challenge first.

reStructuredText:

She *un*\wrapped the challenge first.

Note that the letter w has to be escaped (preceded by a backslash) for reasons explained here. If the letter is not escaped then a warning is displayed and the result is:
She unwrapped the challenge first.

PML:

She {i un}wrapped the challenge first.

Text in Bold And Italic

We want to write:
They were all totally flabbergasted.

HTML:

They were all <b><i>totally flabbergasted</i></b>.

Asciidoctor:

They were all *_totally flabbergasted_*.

reStructuredText:

Combining bold and italic is not supported in reStructuredText, but there are some complicated workarounds.

PML:

They were all {b {i totally flabbergasted}}.

Real-Life Example

Here is an example inspired by an Asciidoctor user who asked how to display:
_id optional.

Let’s make the exercise a little bit more interesting by also displaying:
_id optional.

HTML:

<b>_id</b> <i>optional</i>
<i>_id</i> <b>optional</b>

No surprise here. It just works as expected.

Asciidoctor:

Intuitive attempt:

*_id* _optional_
__id_ *optional*

The first line doesn’t work, it produces:
id _optional

However, the second line works, which is a bit counterintuitive.

If normal text includes a character that is also used for markup (in our case the _ preceding id), then the character must be escaped. This is a fundamental rule in pretty much all markup languages. For example in HTML a &lt; must be escaped with &lt;. Many languages (including Asciidoctor and PML) use a backslash prefix (e.g. \r) to escape. So let's rewrite the code:

*\_id* _optional_
_\_id_ *optional*

This doesn’t work in Asciidoctor. It produces
_id optional
and
_id optional

Here is a correct version, as suggested in an answer to the user’s question:

*pass:[_]id* _optional_
_pass:[_]id_ *optional*

Another answer suggests this solution:

*_id* __optional__
___id__ *optional*

More edge case are documented in chapters Unconstrained formatting edge cases and Escaping unconstrained quotes of the Asciidoctor User Manual.

reStructuredText:

**_id** *optional*
*_id* **optional**

There is no problem here, because the character _ is not used in reStructuredText to define markup.

However, suppose we wanted to write:
id optional.

Here is the code:

*\*id\** ***optional***

Note that the *s in id must be escaped, but the *s in optional don't need to be escaped.

PML:

{b _id} {i optional}
{i _id} {b optional}

Nested Font Styles

Nested font styles of the same kind (e.g. <i>...<i>......) occur rarely in text written by humans, but they could be more or less frequent in auto-generated markup code. If they are not supported then the tool that generates the markup code becomes more complicated to implement, because it must track the font styles that are active already, in order to avoid nesting them.

So, how is this supported in the different languages?

HTML:

<i>This is <i>excellent</i&gt;, isn't it?</i>

No problem, it produces
This is excellent, isn’t it?

Asciidoctor:

_This is _excellent_, isn't it?_

The above code is obviously ambiguous: Are the italics nested or do we want to italicize “This is “ and “, isn’t it?”. When I tested it, the result was neither of it:
_This is excellent, isn’t it?_

As far as I now, Asciidoctor doesn’t support nested font styles of the same kind.

reStructuredText:

The reStructuredText specification states: “Inline markup cannot be nested.” However, no error is displayed if it is nested, and the result is unspecified.

PML:

{i This is {i excellent}, isn't it?}

Font styles of the same kind can be nested in PML. The above code results in:
This is excellent, isn’t it?

Nested Chapters

Suppose we are writing an article titled “New Awesome Product” that contains four chapters. The structure looks as follows:

New Awesome Product
    Introduction
    More features
    Faster
    Less resources

Later on we decide to insert chapter “Advantages” as a parent of the three last chapters. The structure now becomes:

New Awesome Product
    Introduction
    Advantages
        More features
        Faster
        Less resources

What are the changes required in the markup code to pass from version 1 to version 2? Can we simply insert the code for a new chapter? Let’s see.

HTML:

Note: Code changes are displayed in bold.

As shown above, besides inserting the new chapter, we have to change the markup for the three child chapters: h2 must be changed to h3.

Asciidoctor:

Again, we have to change the markup for the three child chapters: == must be changed to ===

Note: The blank lines between the chapters are required, otherwise the document is not rendered correctly.

reStructuredText:

The markup for the three child chapters must be changed: All occurrences of = must be changed to -

The non-trivial rules for reStructuredText’s sections can be looked up here.

PML:

In PML, there is no need to change the code of the three child chapters.

Bottom Line:

In all languages, except PML, the markup code of all child chapters must be adapted if a parent chapter is inserted.

This is not a deal-breaker in case of small articles with few chapters. But image you are writing your next big article or book with lots of chapters and frequent changes. Now, the necessity to manually update child chapters can quickly turn into a daunting, boring, and error-prone task.

Note: Asciidoctor provides a leveloffset variable that can be used to change the level of chapters. This might be useful in some cases, but it also creates additional unneeded complexity, as can be seen here and here.

A more serious kind of problem can arise in the following situation: Imagine a set of different documents that share some common chapters. To avoid code duplication, the common chapters are stored in different files, and an insert file directive is used in the main documents. This works fine as long as the levels of all common chapters are the same in all documents. But troubles emerge if this is not the case.

It is also worth to mention that HTML, Asciidoctor and reStructuredText don’t protect us against wrong chapter hierarchies. For example, you don’t get a warning or error if a chapter of level 2 contains a direct child chapter of level 4.

In a language like PML, the above problems simply don’t exist, because the level is not specified in the markup code. All chapters (of any level) are defined with the same, unique syntax. The chapters’ tree structure (i.e. the level of each chapter) is automatically defined by the parser. And wrong hierarchies in the markup code, such as a missing } to close a chapter, are flagged by an error message.

Lists

In Asciidoctor the kind of problems we have seen with chapter hierarchies can also arise with list hierarchies (e.g. lists that contain lists). The reason is the same as for chapters: Asciidoctor lists use different markup code to explicitly specify the level of list items (* for level 1, ** for level 2, etc.). Moreover, there are a number of complications you have to be aware of when working with complex list content.

In reStructuredText, nested lists are created using indentation and blank lines. This works fine for simple nested lists, but creates other problems in more complex cases (not discussed here). Using whitespace (e.g. blank lines and indentation) to define structure in markup code is a bad idea, as we’ll see soon.

In HTML and PML, the above problems don’t exist with lists because the syntax for parent- and child nodes is the same.

Whitespace And Indentation

At first, using whitespace to define structure seams like a good idea. Look at the following example:

parent
    child 1
    child 2

The structure is very easy to read and write. No noisy special markup characters are needed.

It is therefore tempting for markup language designers to use whitespace as a simple way to define structure. Unfortunately, this works well only for simple structures, and has other inconveniences we’ll see soon.

Therefore, a simple, but important rule must be applied in markup languages designed to work well with complex content:

“Whitespace doesn’t change the structure or semantics of the document.”

— whitespace-insignificant-rule

What does this mean?

First, let us define whitespace: Whitespace is any set of one or more consecutive spaces, tabs, new lines, and other Unicode characters that represent space.

In our context, the above rule means that:

Within text, a set of several (i.e. more than one) whitespace characters is treated the same as a single space character.

For example, this code:

a beautiful
    flower

… is identical to this one:

a beautiful flower

Between structural elements, a set of whitespace characters is insignificant.

For example, this code:

<table>

    <tr>

… is identical to this one:

<table><tr>

A special case of whitespace is indentation (leading whitespace at the beginning of a line). The above rule implies that indentation is insignificant too. Indentation doesn’t change the result of the final document.

Applying the whitespace-insignificant rule is important, because it leads to significant advantages:

• There is no need to learn, apply and worry about complex whitespace rules (see examples below).
  Violating the whitespace-insignificant rule in a markup specification adds unneeded complexity, and can lead to markup code that is ugly, error-prone, and difficult to maintain, especially in the case of nested lists.
• Whitespace can freely be used by authors to format the markup code in a more understandable, presentable and attractive way (pretty printing). For example, lists (and lists of lists) can be indented to display their structure in a visually clear and maintainable way, without the risk of changing the underlying structure.
• Text blocks can be copy/pasted without the need to adapt whitespace.
• If shared text blocks (stored in different files) are imported into several documents with different structures, there is no risk of changing or breaking the structure.
• There is no unexpected or obscure behavior if the whitespace is not visible for human readers. Some examples:
• a mixture of whitespace characters, such as spaces and tabs, especially when used to indent code
• whitespace at the end of a line
• whitespace in empty lines
• visually impaired (blind) people who can’t read whitespace
  Note: To alleviate the pain, some editors provide a display-whitespace mode.
• Tools that generate markup code, as well as markup parsers are generally easier to create.
• In some situations it is useful to reduce whitespace to a minimum (e.g. no new lines), in order to save storage space and improve performance.

If you want a few examples demonstrating the kind of technical problems that arise if whitespace is significant, you can read:

• What are the downsides to whitespace indentation rather than requiring curly braces?
• F# syntax: indentation and verbosity
• Issue in nodeca/js-yaml

So, how is whitespace handled in the languages we are discussing in this article?

HTML:

HTML applies the whitespace-insignificant rule.

For a thorough explanation, look at this excellent article written by Patrick Brosset: When does white space matter in HTML?.

Asciidoctor:

In Asciidoctor, whitespace is significant in some cases.

This can lead to surprising behavior and problems with no easy or no satisfying solution. Some examples can be seen here and here.

reStructuredText:

reStructuredText has whitespace rules that are ‘a bit surprising’.

For example, writing *very* results in very (text in italics, as expected). However, * very* results in very (no italics!), because of the whitespace preceding "very". To understand why, the answer might be found in chapter Whitespace of the specification.

PML:

Similar to HTML, PML applies the whitespace-insignificant rule.

There is one exception: For practical reasons, a blank line between two text blocks results in a paragraph break. This means that instead of writing:

{p text of paragraph 1}
{p text of paragraph 2}

… we can simply write:

text of paragraph 1

text of paragraph 2

Note: Sometimes, whitespace is significant in text. For example whitespace must be preserved in source code examples. Or, in verbatim text, several consecutive spaces or new lines must be preserved in the final document. All languages support this. However, in reStructuredText it’s not always obvious how to it, as shown here.

Other Inconveniences

As seen already, some markup languages systematically use opening and closing tags. An example would be <;i>; and in HTML. All XML-based languages, as well as PML belong to this class of languages.

Without digging into details, here are some drawbacks that can occur in languages that do not (or not always) use pairs of distinct opening/closing tags (e.g. Markdown, Asciidoctor, and reStructuredText):

Editor support
Creating good, reliable editor support is more difficult to develop. Examples of useful editor features are:

• syntax highlighting for markup code
• markup code completion
• visualizing pairs of block start/end marks (e.g. { and its corresponding })
• block collapsing/expanding
  In the case of languages that use distinct opening/closing tags, the two last features work out-of-the-box in some editors. For example, PML uses { and } for node boundaries. This is also used in many programming languages (C, Java, Javascript, etc.) and therefore block features implemented for programming languages will also work for PML.

Document validation
Fewer syntax and structure errors can be detected automatically. This can lead to more time spent on debugging documents. Or, even worse, there might be silently ignored errors that end up in wrong output (Did I really fail to spot the missing warning block on page 267 of my 310 pages book?).

Parsers
It is more difficult to create parsers (i.e. programs that read markup code) that work well in all cases. If different parsers read the same markup code, there is an increased risk of getting different results for corner-cases.

Auto-generated markup code
Tools that generate markup code programmatically are more difficult to create. For example, if whitespace is significant, or font styles cannot be nested, then additional state must be updated and tracked, in order to respect these rules.

My Own Experience

When I started writing technical documents a few years ago, I used Docbook. It took me some time to learn it, but after that I never stumbled on anything I couldn’t do. Docbook is powerful. However, I disliked typing verbose XML code. I tried some XML editors, but gave up. Finally I just wrote complete text blocks unformatted in Notepad++, and then adorned the text with the necessary markup code. It was frustrating and time-consuming. Moreover, I couldn’t find a stylesheet that produced good-looking web documents, and I didn’t have the patience, motivation, and experience to fiddle around with big, complex CSS files and adapt them.

Later on I discovered Asciidoctor. What a relief. Everything was so much simpler and the web documents were beautiful, out of the box. Asciidoctor’s documentation is great, and I think the community is helpful and active. However, when I started to write more complex and bigger documents, I had to deal with problems similar to those described in the previous sections. At one point, I had to develop a specific pre- and post-processor to solve a problem for which I couldn’t find a solution in Asciidoctor/Gitbook.

An intriguing question emerged: “Why do these problems not exist in Docbook?”.

To make a long story short, I concluded that we need a new markup syntax. The key points to success would be:

• easy to learn: few, simple, consistent and predictable rules (no exceptions)
• easy to write and read
• well-structured documents with no ambiguities
• powerful enough to create big, complex documents without the need for “special rules, tricks, or workarounds”

After a period of investigating, pondering, programming, testing and improving, the Practical Markup Language (PML) was born. Since then, I never looked back again. Today I write all my web documents in PML (including this article).

Of course, when I started to create PML, it was to cover my own needs. So, I am probably biased. Hopefully this article contains enough factual examples, but I encourage you to leave a comment if you see anything wrong, unfair, or missing. I appreciate constructive feedback of any kind, and I will update the article if needed.

Conclusion

As demonstrated in this article, a good number of problems encountered with existing document markup languages vanish with the PML syntax.

Now we should come together to improve PML and make it more powerful, so that it covers more use cases and more people can benefit from it.

Please help to spread the word. Or try out PML and send feedback, so that we know what needs to be refined. Your voice counts!

The vision is to create the best possible document markup language and all necessary tools, so that writers can focus on writing and enjoy creating beautiful documents in a minimum of time — without worrying about unneeded complexity.

An explanation of why you might want to dump your word processor.

Introduction

Did you ever wonder what’s the best tool to write an article, user manual, book, or any other kind of text document?

There are many options to choose from. Most people use a What-You-See-Is-What-You-Get (WYSIWYG) editor (also called a text processor), such as Google Docs, LibreOffice or Word. However, more and more people are writing their documents…