how to write markdown documentation

The Markdown Guide is a free and open-source reference guide that explains how to use Markdown, the simple and easy-to-use markup language you can use to format virtually any document.

Get Started

Everything you need to learn Markdown.

Markdown makes writing on the web fast and easy. The Markdown Guide teaches you how to use it.

Learn the ropes.

Start using Markdown right now by following along with the Getting Started guide. It's designed for everyone, even novices.

Dive into the syntax.

Whether you're new to Markdown or a seasoned pro, you'll find the answers to your formatting questions on the basic syntax page .

Take it up a notch.

Make your Markdown documents awesome by using extended syntax to create tables, fenced code blocks, automatic links, and more.

Stay in the loop.

Sign up now to get priority notifications about The Markdown Guide .

• Knowledge Management
• Knowledge base Software
• Technical Documentation
• API Documentation
• Customer Support
• Best Practices
• Product Updates
• Product Engineering

Need an awesome Knowledge base?

We'll show you how to build a knowledge base (public or private) in minutes.

Introductory Guide to Markdown for Documentation Writers

Category: Technical Documentation

Last updated on Jan 10, 2024

Introduction

You may well have heard of Markdown , but it’s okay if you haven’t. The typical way that users first might encounter Markdown is through formatting text on internet message boards. You might have encountered it used on GitHub in readme files, at the very least. A professional use for Markdown is to write technical documentation. Technical writers have a dazzling array of options for producing their documentation. That’s why many writers opt for Markdown – it’s easy to use, and adaptable between different platforms (at least, in theory).

Table of Contents

• What is Markdown?
• The back end of Markdown
• History of Markdown
• Markdown Flavours
• Why Learn Markdown?
• Basics of Markdown
• Intermediate Markdown
• Markdown Editors

1. What is Markdown?

You might be wondering, what the heck is Markdown anyway? Markdown is a lightweight markup language . It allows you to style a digital text document using typical formatting techniques: for example, headings, emphasis, lists, images, and links. Markdown files are stored as .md or .markdown. Also, Markdown can be optionally converted into XHTML or HTML to display nicely in a browser.

Some of the many uses of Markdown are readme files, writing messages in online discussion forums, creating rich text using a plain text editor, emails, and technical documentation. Popular sites that use Markdown include GitHub , Trello , Reddit , SourceForge , and StackExchange , among many others.

You, too, may want to use Markdown for formatting your documentation. It can be hosted by Static Site Generators such as Hugo which are linked with a text editor, or you can use an end-to-end proprietary solution to produce your Markdown files.

This light-weight markup language is a compromise between restrictive WYSIWYG editors, and formatting content directly in HTML. Writers can have as much control over the presentation of their information without resorting to full HTML tagging. At the same time, Markdown parsers also support dropping in blocks of HTML code that add to Markdown’s limited syntax, in case you want to achieve a more complex design 

2. The back end of Markdown

There’s a little more to Markdown than meets the eye. This section helps you understand what’s going on under the hood, in between formatting your Markdown files and the final rendered output for the web.

You don’t necessarily need to know what’s going on behind the scenes, unless you use a combination of tools like a text editor and static site generator, but sometimes it’s good to know!

This process is a mixture of learning the Markdown syntax, and then understanding how that file is then rendered.

1. Create your Markdown file using a text editor or specialised Markdown application 2. Open your Markdown file in a specialised Markdown application 3. Convert your Markdown file to an HTML document using the Markdown application and parser 4. View your HTML file in a web browser

Alternatively, there are resources out there (like Pandoc ) which can convert your Markdown files into other formats, including DOCX, PDF, RTF, ODT, or EPUB. For example, you can convert your Markdown files into an ebook, with each Markdown file functioning as an individual chapter.

Sign up for your 14-day free trial with Document360 now

3. History of Markdown

Markdown was developed by John Gruber in collaboration with Aaron Schwartz in 2004, so it’s got a little bit of history. Gruber was tired of how complicated it was to format his web content using the standard HTML. That’s why he came up with Markdown. “The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.” – John Gruber

Before Markdown, all that was available was other markup languages like HTML and LaTeX. Markdown arose as a lightweight markup language for web writers, many of whom are also developers. That makes Markdown an especially good solution for technical documentation that also requires collaboration with development teams.

Back to the history. Conflicts soon arose concerning Markdown, which suffered from a lack of standardisation for the syntax. There was no Markdown specification, and Gruber remained unwilling to extend the syntax. People ended up developing their own, independent, implementations (also known as “flavours”). This led to problems converting Markdown from one system to another. For example, it’s more difficult than it should be to convert a GitHub wiki to docbook using Pandoc, due to incompatible syntax deviations. Unlike HTML, there is no internet standard for Markdown syntax. So, CommonMark was born as an unofficial initiative established to standardise all the different “flavours” of Markdown. CommonMark is a standard, unambiguous syntax specification for Markdown, alongside a suite of comprehensive tests that validate implementations of Markdown against the specification. That very short summary brings us up to today.

4. Markdown Flavours

As we just mentioned, the unstandardised nature of Markdown has given rise to a number of popular “flavours” – essentially, extensions of the original Markdown syntax. The reason for this is to add extra functionality not available in the original syntax, such as tables, references, and syntax highlighting. Some flavours of Markdown have become very commonly used, such as the GitHub flavour, which is called GitHub Flavored Markdown (GFM). It includes extra features such as tables, programming language selection, and syntax colouring. Taking into account the Markdown flavours, your Markdown files may not always be compatible with different editors if they don’t support the extra syntax used. This lack of consistency among implementations of Markdown is one of the main issues that people have with it. Here’s a list of the most common flavours of Markdown available today.

5. Why Learn Markdown?

Despite having some issues, Markdown is used by many people. You don’t even have to be a developer to pick up the basics. The advantage of Markdown is that once you know how it works, it’s very easy to write. It’s intuitively easy to pick up because it’s based on email formatting conventions that many people have been exposed to already. Markdown offers a smoother workflow than traditional publishing systems. Unlike in a normal writing User Interface, such as Microsoft Word or Google Docs, you don’t have to stop writing to select formatting buttons. Formatting is included in-line with your text, and it looks like the effect it’s intended to create. In other words, a list looks like a list, and **emphasis** looks like emphasis. You can also easily read Markdown in its raw state, unlike for example raw HTML, which is full of tags. The Markdown syntax flows perfectly with the rest of your writing, and it’s intuitively clear what the syntax means. Markdown files are portable, and can be opened in any editor compatible with Markdown, in case you want to change applications. Although in practice, this may not be as simple, it’s a good option to have. Markdown is platform-independent, which means you can create Markdown files in any text editor. It’s useful across many different websites and applications. It’s a reusable skill. Markdown is versatile, so you learn it once, and you can use it for lots of different activities. You can use Markdown to take notes, create content for a website, or produce print-ready documents.

6. Basics of Markdown

It’s worth learning the basic Markdown syntax outlined by John Gruber, which is supported by the majority of Markdown applications. You’re likely to find the syntax of Markdown relatively intuitive to pick up. It’s also possible to write directly in HTML in any Markdown file, if you prefer. You can get started right now with Markdown in the browser using a tool such as Dillinger.

All Markdown files should contain headers. You need a level 1 header for the title of your Markdown file, and at least level 2 headers for the subheadings within the body text. Headings make your text more readable and help to break up the topics. In Markdown, headings are formatted with hashes (#) in front of the line containing your heading. You can use up to six hashes, with the number of hashes corresponding to a heading level. Your text will look like this: # Heading level 1 ## Heading level 2 ### Heading level 3 #### Heading level 4 ##### Heading level 5 ###### Heading level 6

When writing your Markdown body text, you’ll likely want to split your information up into paragraphs (with a noticeable gap between each paragraph). Paragraphs are divided by a blank line (a line containing no characters) between consecutive paragraphs. Your text will look like this: Paragraph 1

Paragraph 2

Line breaks

Sometimes, you’ll want to split your information up by inserting a new line, with less space than you’d get from formatting as a paragraph. This is called a line break. To insert a line break into your Markdown file, finish your line with at least two spaces and press return. This will render a new line for your text. Your text will look like this: Line 1 Line 2

When writing your content in Markdown, you might want to place a bit more emphasis on certain words or phrases. The first way you can emphasise your text is in italics. You can make your text italic by wrapping your text with one asterisk on each side (alternatively, you can use underscores in place of the asterisks). Once your application detects the second asterisk, your formatting for this element is considered “closed”. Your text will look like this: *This text is italic* _This text is also italic_ Bold formatting provides a slightly heavier emphasis than italics, but it works in exactly the same way. This time, use two asterisks to wrap the text you want to make bold (alternatively, you can use underscores in place of asterisks). Your text will look like this: **This text is bold** __This text is also bold__ If you really want to make a point, you can make your text simultaneously bold and italic to give it even more weight! To make your text bold and italic, use three asterisks (or three underscores) to wrap your word or phrase. Your text will look like this: ***This text is italic and bold.*** ___This text is also italic and bold___

Links (inline)

Sometimes we want to link to external websites when writing Markdown content. There’s a simple way to do this using two sets of brackets. To format an inline link in Markdown, you use square brackets to wrap your link text. Place the square-bracket wrapped link text alongside parentheses containing your URL (make sure you don’t include a space between the link text and the link). Your text will look like this: [This is link text](This is a link URL) If you want to add title to your link, insert your alt text next to the link inside quotation marks Your text will look like this: [This is link text](This is a link URL “This is a title”) Note that if you want to link to a local file, within the same server as your other Markdown files, you can format your link with a forward slash followed by the relative URL. Your text will look like this: [This is link text](/This is a relative URL “This is a title”)

A picture is worth a thousand words, as they say. Inserting an image into your Markdown file is similar to the formatting for links.

Begin your image formatting with an exclamation mark. Next, use square brackets to wrap your image alt text, next to parentheses containing the URL for your image. Ensure there are no spaces between the exclamation mark, square brackets, or parentheses.

Your text will look like this:  When your Markdown file is rendered to HTML, the image will be embedded directly into the body text.

Unordered lists Sometimes, you may want to format your content in lists to make it easier to read.

The first option is to use an unordered list, where each item on your list is preceded by a bullet point. Markdown allows you to format your lists with a number of different symbols: asterisks (*), hyphens (-) or plus signs (+).

It’s up to you to choose which symbol you prefer. The result you get is the same. Here is an example list: * This is a list item * This is a list item * This is a list item * This is a list item Ordered lists Other times, you may want to present your information sequentially in ordered lists (1, 2, 3, and so on). Format your ordered lists by preceding each list item with a number, followed by a full stop and then a space.

In Markdown, it doesn’t matter which numbers you use to format your list, as the list will always render as 1, 2, 3, and so on. Your text will look like this: 1. This is a list item 2. This is a list item 3. This is a list item 4. This is a list item

Blockquotes

Sometimes in Markdown, we will want to reference an external source using quotation marks. This is called a blockquote. You represent any blockquote by preceding the first line of the block quote with a greater-than sign or angle bracket (>). Gruber recommends inserting the angle bracket before every line of your blockquote.

Your text will look like this: > This is a blockquote > This is a blockquote > This is a blockquote

7. Intermediate Markdown

Now you’ve got to grips with basic Markdown, you might want to attempt some slightly more advanced formatting.

Horizontal rules

A horizontal rule is a useful little element that you can use to visually split up blocks of text within your Markdown file. A horizontal rule is represented by three or more hyphens (-), asterisks (*), or underscores (_). Whichever symbol you use renders the same output.

Your text will look like this: —

Code blocks and snippets

Code snippets Often when we’re writing in Markdown, we need to reference snippets of code as examples. This is particularly common in technical documentation. Markdown allows you to format code snippets using backticks (`) that wrap your code snippet. The first backtick “opens” the snippet, and the second backtick “closes” it.

Your text will look like this: `This is a code snippet` Code blocks Formatting code blocks is useful when you have a bigger chunk of code to include in your Markdown file. Format your code blocks by indenting every line of your code block using one tab, or four spaces. This is a code block This is a code block This is a code block Remember, some extensions of Markdown, such as GitHub Flavored Markdown, support programming language selection and syntax colouring. Original Markdown does not support these styles.

Reference-style links

There may come a time in your Markdown writing career that you want to include reference-style links. Instead of inserting your URL inline alongside your link text, the link is listed elsewhere in the Markdown file (usually below the paragraph containing the link, or at the end of the document). Formatting your links in this way makes your Markdown content easier to read. Format your reference-style links by enclosing your link text in square brackets, followed by your label in another set of square brackets. The label acts as an anchor. Your text should look like this: [This is link text][This is a label] You format the second part of the link (placed at the end of the paragraph, or bottom of the file) using three attributes. 1. Your label in square brackets, followed by a colon and at least one space 2. Your link URL 3. An optional link title, enclosed in either double quotes, single quotes, or parentheses Your text will look like this: [This is a label]: This is an URL “This is a link title” Most people will list their links in the order they are referenced within the file.

Often in Markdown, you will need to include characters in your text (for example, and asterisk) that may be part of the Markdown syntax. You need to “escape” these characters so your Markdown application doesn’t read these characters as formatting. You escape characters in Markdown using a backslash before the character, with no space in between. Your text should look like this: \* You can escape any of these characters: \ backslash ` backtick * asterisk _ underscore {} curly braces [] square brackets () parentheses # hash symbol + plus sign – minus sign (hyphen) . dot ! exclamation mark Lists within blockquotes Sometimes, you might want to insert a blockquote into your Markdown that contains another element, such as an unordered list. You need to nest your list formatting inside your blockquote formatting. Format your blockquote using a greater-than sign (>) followed by a space, including a sign before every line of your block quote. Add your list formatting (*) just after your greater-than signs. Your text should look like this: > This is a blockquote > * This is a list item within a blockquote > * This is a list item within a blockquote > * This is a list item within a blockquote

You can insert HTML elements directly into your Markdown file. For example, you may want to include a button. Insert your HTML exactly as you would in any other HTML document. Your text should look like this: <button>This is a button</button> This formatting also works for your other Markdown syntax, such as emphasis. Instead of **This element is bold**, you could format it in HTML as <bold>This element is bold</bold>.

8. Markdown Editors

Markdown is supported by a variety of different systems, from text editors combined with Static Site Generators to dedicated Markdown web applications. Some editors come built in with basic Markdown capabilities, even if they were not specifically designed for Markdown. Others are designed to extend the Markdown syntax, such as Ghost. There are Markdown editors for different operating systems (MacOS, Linux, or Windows), or alternatively you can use a web-based application. Here’s a compilation of some of the most popular Markdown editors organised by system:

• ghostwriter
• Markdown Monster

iOS/Android

• Blot.im – platform for blogging
• Smallvictori.es – platform that makes a website using DropBox
• StackEdit – in-browser Markdown editor that supports different Markdown flavours
• Dillinger – browser-based Markdown editor
• Ghost – browser-based blogging platform

Static Site Generators

• Docusaurus We’d also like to put forward our own Document360 knowledge base software, which offers a Markdown editor for formatting your documentation.

Final Remarks

There are many possibilities for your work in Markdown, beginning with simple note-taking, to blogging and progressing right through to professional technical documentation . By learning the basics of Markdown, you are opening yourself up to smoother formatting and publishing. The number of applications supporting Markdown is only increasing, making it a very good choice for your documentation. Why not trial Document360 , which comes with an in-built Markdown editor, for your documentation 

Downloadable cheat sheet

Catherine Heath

Jan 31, 2020

Access actionable resources on technical documentation

By signing up, you agree to our Terms , Policy and GDPR

Share this Article

Related Articles

Thank you for subscribing.

You will be receiving an email from us shortly.

Fill in the details to view the report

Getting Started With Markdown [Beginner's Guide]

In my work, I often have to write code, write the documentation that goes with that code, create Web pages, and work on text restoration projects, and have written several formal papers while I was in school. I can include class notes here, too; I needed to write them for nearly every class.

I use Markdown for nearly all of my writing and it is a major time-saver for me.

In this article, I am going to share my experience with Markdown. You’ll be learning the following:

What is Markdown?

• How does it work?
• Markdown basic syntax and how to use them

If you are new to Markdown, it is a text-to-HTML conversion tool for web writers. Markdown files follow a specific syntax that is easy to read and just as easy to write. They are plain text files so they can be created using any text editor on any computer. These files can then be turned into Web pages – and Web pages are built using a markup called HTML.

Markdown then, is just a way to create Web pages without the need (or even know how) to write HTML code. Actually, Markdown is an great way to format plain text even if you don’t have to convert to HTML. Someone once described Markdown to me this way:

It isn’t what you see is what you get , but what you see is what you mean

Markdown, however, is more than an easy formatting scheme, it is also a software tool that converts plain text formatting to HTML.

This is why the syntax is important. If you want a title on your Web page, Markdown will create one based on the character(s) you use in front of your title. A sampling of some of Markdown’s syntax is shown this screenshot:

So how do I make this plain text to HTML conversion?

John Gruber’s Markdown is a Perl script that is run on the command line. Basically, it reads the Markdown text that you create and builds a Web page from it.

I will avoid the command line here since there are many outstanding Markdown editors that can do this conversion for you. Not only that, many of these editors will let you write your text and show you what the Web page will look like (called rendering ) at the same time.

Markdown editors are generally set up to show two frames. The left frame is where you write your text and the right frame shows you what the formatted text will look like in HTML:

When you are finished with your text and are happy with it, simply save the Markdown file. This way, you’ll always have it in case you need to edit or rewrite later. Once the file is saved, you can have the editor export the markdown file to HTML.

The editor will create the Web page, using your Markdown as a reference. Your Markdown file will not be changed during an export – you will still have it – along with a separate, newly created HTML (Web page) file that you can put on a Web server.

Note : Many Markdown editors can also export your Markdown files to other formats, such as .doc , .docx , and .pdf . You can learn about those advanced setups, and extra software you might need, later on.

Basic Markdown Syntax

To get the new Markdown user up to speed quickly, I will limit this to cover the syntax I use most often. These, I believe will be the most helpful – you can be productive now while you learn more about what Markdown can do for you later on.

Write Headings

I normally use # characters to denote headings. There are six levels:

There is another heading style that uses lines underneath the text. I rarely use this type of heading since I am limited to only two. A double line, which is made with the = character, makes a H1 heading. A single line, made with the - character, makes a H2 heading:

Paragraphs are separated by a blank line (make sure that there is a blank line between paragraphs). Do not indent the first line at all. Indenting with a <Tab> or <spaces> has a different purpose in Markdown.

A paragraph is a block of text and should not be indented with spaces or tabs. It can have one line or many lines. To end a paragraph and start a new one, the <Enter> key is hit twice; paragraphs are separated by a blank line.

Line Breaks

Remember that with paragraphs, a blank line has to separate them and this is done by pressing twice on the <Enter> key. Markdown is strict about it.

Markdown does not support “hard-wrapped” or “fixed-line-length” paragraphs. That is, hitting the <Enter> key once will not force text to a new line. It may appear so in the editing window, but the HTML won’t show it.

Yet, there will be times when you may need to break up paragraphs with some way to break up a line. Markdown does have a way to do this but it may seem a little strange at first: a line break is made by ending a line with two or more spaces and then hitting the <Enter> key once.

Here is a working example of a short verse. Each line has two spaces at the end. The last line, since it’s the end of the verse, doesn’t have the extra spaces. Since it’s the end of the verse (paragraph), I hit the <Enter> key twice:

Baa, baa black sheep, Have you any wool?. Yes, sir. Yes, sir. Three bags full.

Adding two spaces at the end of a line, to create a line break, can take some getting used to.

Horizontal Rules

Horizontal rules are great for splitting up text into sections.

Use three or more dashes - , underscores _ , or asterisks * for horizontal rules, like so:

You can even put spaces between the characters:

I do not use horizontal rules very often in articles or papers, but they come in handy for me in journal entries, system logs, and class notes.

Emphasis on text with bold and italics

When you want a word or phrase to stand out and be noticed, you can either make it bold or italicized. Italics and bold text can be made on one of two ways. The first is by surrounding the text with asterisks * , while the second is to use underscores _ .

To italicize a word or phrase, surround the text with one underscore or asterisk. To make a word or phrase bold, surround it with two underscores or asterisks:

Remember to use the same character. An asterisk on one side of a word or phrase, and an underscore on the side, will not work. The same character has to be on both sides of the word or phrase.

Block quotes

Block quotes are used for direct quotes. If you were writing a blog entry and you wanted to repeat something that Benjamin Franklin said, you could use a block quote.

A right angle bracket is used to specify a block quote:

Adding links in Markdown

Links are just plain cool. There are three ways to create links on basic Markdown, but I will only cover two here: Regular links and automatic links.

The third type of link, called reference links, are supported in basic Markdown and more advanced flavors. I want to get to started quickly. You can look up reference links when you are ready for that.

Regular links let you link to various websites. The name of the site, or a phrase you want to use, is placed in square brackets [] . The actual link is inside parentheses () .

Automatic links are made with angle brackets <> surrounding the link. The link is an actual address (either a Web or email address). The link is spelled out and, when it is converted to HTML, the spelled out link becomes a working link.

This is useful for when you want to spell out the address in your text:

Adding images in Markdown

Links to images are almost identical to links to Web sites. The small difference between site links and images, is that image links begin with a bang (exclamation point) !

The name of the image, or a descriptive phrase of the image, is placed in square brackets [] . The actual link is inside parentheses () .

You can embed images like so:

Here’s an example image link. It is a sample link, with no image, but it is a decent sample of how an actual link might look like:

Lists are made for many reasons. They can be used as ‘things to do’ items, topic elements in an outline, parts lists in an assembly project, and so on. There are two main types of lists: unordered and ordered.

Unordered lists are not numbered; these are the ‘bullet items’ we see in many documents. Ordered lists are numbered.

To create an ordered (numbered) list, just begin each line with a number, like so:

Unordered lists are not numbered, but use either an asterisk * , a plus sign + , or a minus sign - at the beginning of each item on the list. I prefer to use either an asterisk or minus sign, but you get to choose:

Sub-items can be added to both ordered and unordered lists by indenting, like so:

Markdown syntax cheat sheet

For your reference, here is a short listing of Markdown syntax that has been covered in this small introduction.

If you decide to adopt it as a writing tool, you’ll find that Markdown has the means to simplify writing even more.

Markdown can do more than what I have described here. A huge percentage of my writing can be accomplished with the Markdown syntax I have covered here – and these are the items I use most often even in more complex projects.

If all of this seems too simple, it really is that easy. Markdown was built to simply the writing task, but you don’t have to take my word for it. Try it out! There is no need to install a Markdown editor; you can do this online. There are several good online Markdown editors . Here are three that I prefer:

John Gruber’s Dingus , Editor.md , and Dillinger . Editor.md and Dillinger will let you see your Markdown rendered as HTML in real time. Dingus doesn’t preview in real time, but there is a Markdown syntax cheat sheet on the page for reference.

Try out some of the examples in this article on either of these online editors. Try out some of your own ideas, too. This will let you get used to Markdown before possibly committing to learn more about it.

And if you want to support It’s FOSS, you can buy our Markdown guide in PDF and EPUB format. It covers what you just learned with a bit more explanation and examples.

Bill has worked as a technician, programmer, and UNIX sysadmin. He is currently a continually caffeinated programmer who spends spare time building e-books for friends and restoring old text.

Complete Guide to Installing Linux on Chromebook

How to install and use conky in ubuntu linux, getting started with ubuntu, understanding ubuntu’s repository system, introduction to bash scripting, it's foss.

Making You a Better Linux User

Great! You’ve successfully signed up.

Welcome back! You've successfully signed in.

You've successfully subscribed to It's FOSS.

Your link has expired.

Success! Check your email for magic link to sign-in.

Success! Your billing info has been updated.

Your billing was not updated.

• Skip to main content
• Skip to search
• Skip to select language
• Sign up for free
• English (US)

How to write in Markdown

This page describes how we use Markdown to write documentation on MDN Web Docs. We have chosen GitHub-Flavored Markdown (GFM) as a baseline, and added some extensions to support some of the things we need to do on MDN that aren't readily supported in GFM.

Baseline: GitHub-Flavored Markdown

The baseline for MDN Markdown is GitHub-Flavored Markdown (GFM): https://github.github.com/gfm/ . This means that you can refer to the GFM specification for anything not explicitly specified in this page. GFM in turn is a superset of CommonMark ( https://spec.commonmark.org/ ).

The GFM specification defines two basic types of links:

• inline links , in which the destination is given immediately after the link text.
• reference links , in which the destination is defined elsewhere in the document.

On MDN we allow only inline links.

This is the correct way to write GFM links on MDN:

This is an incorrect way to write links on MDN:

Example code blocks

In GFM and CommonMark, authors can use "code fences" to demarcate <pre> blocks. The opening code fence may be followed by some text that is called the "info string". The specification states the following:

The first word of the info string is typically used to specify the language of the code sample, and rendered in the class attribute of the code tag.

It's permissible for the info string to contain multiple words, like:

On MDN, writers will use code fences for example code blocks. They must specify the language of the code sample using the first word of the info string, and this will be used to provide syntax highlighting for the block. The following words are supported:

• js - JavaScript
• ts - TypeScript
• jsx - React JSX
• tsx - React TSX
• java - Java
• python - Python
• rust - Rust
• glsl - GLSL (OpenGL Shaders)
• sql - SeQueL commands
• wasm - WebAssembly
• webidl - Web Interface Definition Language
• scss - Sass (SCSS)
• less - Less
• html - HTML
• mathml - MathML
• md - Markdown
• latex - LaTeX
• bash - Bash/Shell
• batch - Batch (Windows Shell)
• powershell - PowerShell
• json - JSON
• yaml - YAML
• toml - TOML
• sql - SQL Database
• ignore - Gitignore file
• apacheconf - Apache configuration
• nginx - NGINX configuration
• django - Django templates
• svelte - Svelte templates
• handlebars - Handlebars templates
• pug - Pug templates (which may be used by Express )
• plain - Plain text
• diff - Diff file
• http - HTTP headers
• regex - Regex
• uri - URIs and URLs

For example:

If the highlighting that you wish to use is not listed above, you should markup the code block as plain . Additional languages may be requested in the process discussed on GitHub .

Suppressing linting

Writers can add a -nolint suffix to any of the language identifiers:

Code blocks like this will get appropriate syntax highlighting and will be recognized by the live sample system, but will be ignored by linters or automatic formatters like Prettier. Authors should use this suffix for showing invalid code or alternative formatting that linters or formatters should not fix.

Additional classes (info strings)

GFM supports info strings , which allow authors to supply additional information about a code block. On MDN, info strings are converted into class names.

Writers will be able to supply any one of the following info strings:

• example-good : style this example as a good example (one to follow)
• example-bad : style this example as a bad example (one to avoid)
• hidden : don't render this code block in the page. This is for use in live samples.

These will be rendered as:

Discussion reference

This issue was resolved in:

• https://github.com/mdn/content/issues/3512
• https://github.com/mdn/yari/pull/7017

Notes, warnings, and callouts

Sometimes writers want to call special attention to a piece of content. To do this, they will use a GFM blockquote with a special first paragraph. There are three types of these: notes, warnings, and callouts.

• To add a note, create a GFM blockquote whose first paragraph starts with **Note:** .
• To add a warning, create a GFM blockquote whose first paragraph starts with **Warning:** .
• To add a callout, create a GFM blockquote whose first paragraph starts with **Callout:** .

Notes and warnings will render the Note: or Warning: text in the output, while callouts will not. This makes callouts a good choice when an author wants to provide a custom title.

Processing of the markup works on the AST it produces, not on the exact characters provided. This means that providing <strong>Note:</strong> will also generate a note. However, the Markdown syntax is required as a matter of style.

Multiple lines are produced by an empty block quote line in the same way as normal paragraphs. Further, multiple lines without a space are also treated like normal Markdown lines, and concatenated.

The blockquote can contain code blocks or other block elements.

This will produce the following HTML:

This HTML will be rendered as a highlighted box:

Note: This is how you write a note.

It can have multiple lines.

Warning: This is how you write a warning.

It can have multiple paragraphs.

This is how you write a callout.

Translated warning

Because the text "Note:" or "Warning:" also appears in the rendered output, it has to be sensitive to translations. In practice this means that every locale supported by MDN must supply its own translation of these strings, and the platform must recognize them as indicating that the construct needs special treatment.

The localizations are stored in Yari as JSON files in gettext format. Refer to these files to determine what string should be used in place of "Note:" or "Warning:" for that locale. If a locale file is not defined, English will be used as a fallback.

For example, if we want to use "Warnung" for "Warning" in German, then in German pages we would write:

And this will produce:

Note containing a code block

This example contains a code block.

This HTML will be rendered as with a code block:

It can contain code blocks.

This issue was resolved in https://github.com/mdn/content/issues/3483 .

Definition lists

Definition lists are commonly used across MDN, but are not supported by GFM. MDN introduces a custom format for definition lists, which is a modified form of a GFM unordered list ( <ul> ). In this format:

• The GFM <ul> contains any number of top-level GFM <li> elements.
• Each of these top-level GFM <li> elements must contain, as its final element, one GFM <ul> element.
• This final nested <ul> must contain a single GFM <li> element, whose text content must start with ": " (a colon followed by a space). This element may contain block elements, including paragraphs, code blocks, embedded lists, and notes.

Each of these top-level GFM <li> elements will be transformed into a <dt> / <dd> pair, as follows:

• The top-level GFM <li> element will be parsed as a GFM <li> element and its internal contents will comprise the contents of the <dt> , except for the final nested <ul> , which will not be included in the <dt> .
• The <li> element in the final nested <ul> will be parsed as a GFM <li> element and its internal contents will comprise the contents of the <dd> , except for the leading ": ", which will be discarded.

For example, this is a <dl> :

In GFM/CommonMark, this would produce the following HTML:

On MDN, this would produce the following HTML:

Definition lists written using this syntax must consist of pairs of <dt> / <dd> elements. Using this syntax, it's not possible to write a list with more than one consecutive <dt> element or more than one consecutive <dd> element: the parser will treat this as an error. We expect almost all definition lists on MDN will work with this limitation, and for those that do not, authors can fall back to raw HTML.

This is not permitted:

As a workaround for cases where an author needs to associate multiple <dt> items with a single <dd> , consider providing them as a single <dt> that holds multiple terms, separated by commas, like this:

The rationale for the syntax described here is that it works well enough with tools that expect CommonMark (for example, Prettier or GitHub previews) while being reasonably easy to write and to parse.

This issue was resolved in https://github.com/mdn/content/issues/4367 .

GFM provides a syntax for creating tables , which we make use of in MDN. However, there are times when GFM tables do not suit our needs:

• The GFM syntax only supports a subset of the features available in HTML. If you need to use table features that are not supported in GFM, use HTML for the table.
• If the GFM representation of the table would be more than 150 characters wide, use HTML for the table.
• We support a special kind of table called a "properties table", which has its own CSS class and is therefore always HTML.

So the general principle is that authors should use the GFM Markdown syntax when they can, and fall back to raw HTML when they have to or when HTML is more readable. For more information, see When to use HTML tables .

GFM table syntax style

In GFM table syntax, authors can omit leading and trailing pipes for rows. However, for the sake of readability, MDN authors must include these pipes. Additionally, authors must provide trailing spaces in rows, so that all cells in a column are the same length in plain text.

That is, MDN authors must use this style:

and not this style:

Luckily, table formatting is auto-fixed by Prettier, so authors may rely on Prettier to format their tables properly.

When to use HTML tables

There are three main circumstances in which authors should use HTML tables rather than GFM syntax:

• The table uses features that are not supported in GFM (see below).
• The GFM table would be too wide to be readable.
• The writer wants a special type of table called a "properties table".

Table features that are not supported in GFM

The main limitations of GFM table syntax are:

• GFM tables must have a header row.
• GFM tables may not have a header column.
• GFM won't parse GFM block elements in table cells. For example, you can't have a list in a table cell.
• GFM tables cannot have classes assigned to them.
• GFM doesn't support any table elements beyond <table> , <tr> , <th> , and <td> .
• GFM doesn't support any table element attributes like colspan , rowspan , or scope .

If an author needs to use any of the unsupported features, they should write the table in HTML.

Note that we don't recommend the general use of <caption> elements on tables, since that would also rule out the GFM syntax.

GFM table maximum width

Even when a table could be written in GFM it is sometimes better to use HTML, because GFM uses an " ASCII art" approach to tables that is not readable when table rows get long. Consider the following table:

In GFM this will look like:

In a case like this it would be better to use HTML.

This leads us to the following guideline: if the Markdown representation of the table would be more than 150 characters wide, use HTML for the table .

Properties tables

Properties tables are a specific type of table used for displaying structured property-value content across a set of pages of a particular type. These tables have two columns: the first column is the header column and lists the properties, and the second column lists their values for this particular item. For example, here's the properties table for the PannerNode interface:

These pages can't be represented in GFM because they have a header column, so writers should use HTML in this case. To get the special styling, writers should apply the "properties" class to the table:

This issue was resolved in https://github.com/mdn/content/issues/4325 , https://github.com/mdn/content/issues/7342 , and https://github.com/mdn/content/issues/7898#issuecomment-913265900 .

Superscript and subscript

Writers will be able to use the HTML <sup> and <sub> elements if necessary, but should use alternatives if possible. In particular:

• For exponentiation, use the caret: 2^53 .
• For ordinal expressions like 1 st , prefer words like "first".
• For footnotes, don't mark up the footnote references, e.g., ^[1] .

This issue was resolved in https://github.com/mdn/content/issues/4578 .

Page summary

The page summary is the first "content" paragraph in a page—the first text that appears after the page front matter and any sidebar or page banner macros.

This summary is used for search engine optimization (SEO) and also automatically included alongside page listings by some macros. The first paragraph should therefore be both succinct and informative.

This issue was resolved in https://github.com/mdn/content/issues/3923 .

Writers will be able to include KumaScript macro calls in prose content:

See Using macros for more information on macros.

Learn Mastering Markdown

Markdown is a lightweight and easy-to-use syntax for styling all forms of writing on the GitHub and other code storage platforms.

Markdown is a lightweight and easy-to-use syntax for styling all forms of writing on the GitHub platform.

What you will learn:

• How the Markdown format makes styled collaborative editing easy
• How Markdown differs from traditional formatting approaches
• How to use Markdown to format text
• How to leverage GitHub’s automatic Markdown rendering
• How to apply GitHub’s unique Markdown extensions

What is Markdown?

Markdown is a way to style text on the web. You control the display of the document; formatting words as bold or italic, adding images, and creating lists are just a few of the things we can do with Markdown. Mostly, Markdown is just regular text with a few non-alphabetic characters thrown in, like # or * .

You can use Markdown most places around GitHub:

• Comments in Issues and Pull Requests
• Files with the .md or .markdown extension

For more information, see “ Writing on GitHub ” in the GitHub Help .

• Headers & Quotes

Sometimes you want numbered lists:

Sometimes you want bullet points:

• Start a line with a star

Alternatively,

• Dashes work just as well

If you want to embed images, this is how you do it:

Structured documents

Sometimes it’s useful to have different levels of headings to structure your documents. Start lines with a # to create headings. Multiple ## in a row denote smaller heading sizes.

This is a third-tier heading

You can use one # all the way up to ###### six for different heading sizes.

If you’d like to quote someone, use the > character before the line:

Coffee. The finest organic suspension ever devised… I beat the Borg with it. - Captain Janeway

There are many different ways to style code with GitHub’s markdown. If you have inline code blocks, wrap them in backticks: var example = true . If you’ve got a longer block of code, you can indent with four spaces:

GitHub also supports something called code fencing, which allows for multiple lines without indentation:

And if you’d like to use syntax highlighting, include the language:

GitHub supports many extras in Markdown that help you reference and link to people. If you ever want to direct a comment at someone, you can prefix their name with an @ symbol: Hey @kneath — love your sweater!

But I have to admit, tasks lists are my favorite:

• This is a complete item
• This is an incomplete item

When you include a task list in the first comment of an Issue, you will see a helpful progress bar in your list of issues. It works in Pull Requests, too!

And, of course emoji!

Syntax guide

Here’s an overview of Markdown syntax that you can use anywhere on GitHub.com or in your own text files.

Blockquotes

Inline code, github flavored markdown.

GitHub.com uses its own version of the Markdown syntax that provides an additional set of useful features, many of which make it easier to work with content on GitHub.com.

Note that some features of GitHub Flavored Markdown are only available in the descriptions and comments of Issues and Pull Requests. These include @mentions as well as references to SHA-1 hashes, Issues, and Pull Requests. Task Lists are also available in Gist comments and in Gist Markdown files.

Syntax highlighting

Here’s an example of how you can use syntax highlighting with GitHub Flavored Markdown :

You can also simply indent your code by four spaces:

Here’s an example of Python code without syntax highlighting:

If you include a task list in the first comment of an Issue, you will get a handy progress indicator in your issue list. It also works in Pull Requests!

You can create tables by assembling a list of words and dividing them with hyphens - (for the first row), and then separating each column with a pipe | :

Would become:

SHA references

Any reference to a commit’s SHA-1 hash will be automatically converted into a link to that commit on GitHub.

Issue references within a repository

Any number that refers to an Issue or Pull Request will be automatically converted into a link.

Username @mentions

Typing an @ symbol, followed by a username, will notify that person to come and view the comment. This is called an “@mention”, because you’re mentioning the individual. You can also @mention teams within an organization.

Automatic linking for URLs

Any URL (like http://www.github.com/ ) will be automatically converted into a clickable link.

Strikethrough

Any word wrapped with two tildes (like ~~this~~ ) will appear crossed out.

GitHub supports emoji !

To see a list of every image we support, check out the Emoji Cheat Sheet .

Download Markdown Cheatsheet PDF

Markdown Cheat Sheet – How to Write Articles in Markdown Language

As a developer, you have likely heard of HTML , which stands for H yper T ext M arkup L anguage.

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.

But markup languages use tags like:

• <p> </p>  is a paragraph tag.
• <b> </b> 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.

#### H4 tag

##### H5 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 2 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 2 .

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.

• Spring onions

And this is how you create it in markdown:

How to Make an Ordered List in Markdown

This is how the ordered list looks.

• 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:

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:

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:

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).

```javascript 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

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.

Senior Software Engineer working on mobile, web and iOS.

If you read this far, thank the author to show them you care. Say Thanks

Learn to code for free. freeCodeCamp's open source curriculum has helped more than 40,000 people get jobs as developers. Get started

Existing customer? Sign in

How to Write Faster, Better & Longer: The Ultimate Guide to Markdown

It’s no secret that we’re big fans of Markdown at Ghost . We built our editor to work with Markdown directly!

Once you get the hang of Markdown, it’s an incredibly powerful writing tool which will allow you to write rich content for the web far faster than almost any other method. To get to that point, however, there’s a little bit of a learning curve. We thought we’d put together an all inclusive guide to make that curve a little bit shorter, and potentially teach you a few super-user tricks to Markdown that you might not have known.

What is Markdown

Markdown is a plain text formatting syntax for writers. It allows you to quickly write structured content for the web, and have it seamlessly converted to clean, structured HTML.

Back in 2004, Apple pundit John Gruber came up with the idea after becoming frustrated by writing long, laborious HTML tags to properly format his content. He devised a simple writing system which would make web based documents both easier to write, and easier to read in their raw state.

Here’s a quick example of Markdown in action:

The quick brown fox, jumped over the lazy dog .

With just a couple of extra characters, Markdown makes rich document formatting quick and beautiful.

Why do Writers Love Markdown so Much?

“Is that it?” - I hear you ask - “I could just click on a few formatting buttons in most editors and achieve the same thing!”

Very true! But we’re only just getting started. The range of formatting tools has come a very long way since Markdown’s inception in 2004, so you’d be forgiven for wondering what advantages it holds over, say, the “Bold” button in Microsoft Word.

While most novice users do indeed find buttons a bit easier to use, advanced writers often swear by Markdown and nothing else. Why? The biggest reason is writing flow .

Using a traditional writing user interface you have to pause your writing every few minutes (or sometimes seconds) and reach for the mouse in order to click, highlight, click a formatting button, and then click back to where you left off in order to continue. This process creates a tiresome, disjointed experience when all you want to do is get the words out of your head and onto the screen.

Markdown allows you to keep your fingers firmly planted on the keyboard as you apply formatting on the fly. In short: You never have to stop typing or think about anything else in order to apply your styles.

It might seem like a small detail, but it can have a really big effect. Once you start writing in Markdown, it’s really hard to back to the click-fest of the past.

Basic Markdown Formatting

Ok! You’re sold. So how does this work? Let’s dive in:

Markdown was designed with the explicit intention to be easily readable by humans. You should find that most of the syntax is pretty simple and intuitive.

Here are the elements you’ll use most often:

Headings in Markdown are any line which is prefixed with a # symbol. The number of hashes indicates the level of the heading. One hash is converted to an h1 , two hashes to an h2 and so on. There are a total of 6 levels which you can make use of - but for most writing, you’ll rarely ever need more than 3.

If you want to emphasise a word a little bit, wrap it in asterisks. For something that needs more emphasis: double asterisks. If you really want to drive the point home, use triple asterisks. If you prefer, you can also use underscores - they’re completely interchangeable.

To add a link: wrap the text which you want to be linked in square brackets, followed by the URL to be linked to in parenthesis. An easy way to remember this one is to think of it like turning a word into a button. [button] and (place to go when the button is clicked) combine to form a link .

Markdown images have exactly the same formatting as a link, except they’re prefixed with a ! . This time, the text in brackets is the alt text - or the descriptive text for the image.

In most Markdown editors, you don’t have to write this code out. They will provide a tool to allow you to upload an image and insert this code automatically. After that, it will appear in your document.

Lists are a formatting nightmare in HTML, but Markdown lists are incredibly easy to manage. For a bullet list, just prefix each like with a * - or - or + and they will be converted to dots. You can also create nested lists; just indent a line with 4 spaces and it will be nested under the line above.

For numbered lists, do exactly the same thing - but use numbers!

When you want to add a quote in Markdown, it’s exactly the same as the formatting which you may already be familiar with from your email app of choice when you reply to someone.

To be or not to be, that is the question.

Prefixing the line with a > converts it into a block-quote.

How can I remember all the Markdown syntax?!

It seems a little daunting at first, but you might be surprised how naturally it comes to you after a couple of posts written in Markdown. Most good Markdown editors come with a built-in cheat sheet to make it a little easier to learn.

Here’s the one you can pull up from the Ghost editor at any time if you get stuck.

Intermediate Markdown Formatting

So you’ve got the Markdown basics nailed and you want to move on to bigger and better things? Excellent. There’s much more we can do.

Horizontal Rules

Want to throw-down a quick divider in your article to denote a visual separation between different sections of text? No problem. 3 dashes produce:

A sleek <hr> element.

Code Snippets

If you’re a technical writer, you may want to use example snippets of code to teach your readers a particular syntax (like I’m doing, with this very blog post). Using a single back-tick around a word in a sentence, you can show a quick code snippet.

Indenting by 4 spaces will turn an entire paragraph into a code-block.

Reference Lists & Titles

If you prefer to use reference lists for your attribution, Markdown can handle this, too. In the above example, all of the links are kept separate in Markdown (so it's easy to read even in its raw format), and then inserted directly as normal links when converted to HTML.

The quick brown fox , jumped over the lazy dog .

You'll also notice that we've added a title attribute to the links by adding a "word" in quote marks just after the URL. Anywhere you use a URL, you can follow it with a "title in quotation marks" to generate a title attribute.

What if you literally want to type *literally* - without it appearing in italics? Escaping Markdown characters with a back-slash \ allows you to use any characters which might be getting accidentally converted into HTML.

Embedding HTML

Possibly the coolest feature of Markdown is that it also just supports plain old HTML. If you find yourself stuck and unable to do what you want in Markdown - you can simply write in regular HTML and it will work just fine.

Big Fat Button

In the above example, I know that within this blog's stylesheet is the CSS to style a nice button that with a class attribute.

So you can drop in any HTML, sharing button, JavaScript snippet or iFrame you like and it will work on the page just as normal.

Advanced Markdown

Ok, you want the big guns. Every example so far has been vanilla, normal Markdown. Those code snippets will work absolutely anywhere which supports Markdown syntax.

Now we're going to look at some syntax which is not standard to native Markdown. They're extensions of the language. All of these things work in Ghost , but they may not work in other editors.

Here are some nice advanced things you can do with Markdown in Ghost:

Strike-throughs

deleted words

Automatic Links

https://ghost.org

Markdown Footnotes

The quick brown fox [1] jumped over the lazy dog [2] .

Syntax Highlighting

Combined with Prism.js in the Ghost theme:

Speed up Your Workflow with Markdown Keyboard Shortcuts

Writing Markdown is pretty quick right out of the box, but you can speed it up even further by getting to know the keyboard shortcuts in your editor of choice. These all tend to be a little different, but in Ghost you can access some on-the-fly formatting very easily:

• Ctrl + B for Bold
• Ctrl + I for Italic
• Ctrl + K for a link
• Tap Ctrl + H multiple times for the most common H2 and H3

There are lots more included in the Markdown Help overlay in the editor. Regardless of which app you use to write, it's work figuring out the Markdown keyboard shortcuts available to speed up your workflow.

Converting HTML to Markdown

If you're just getting into Markdown and you've found yourself with a massive back-log of old files which are written in HTML, you might want to convert them to Markdown to make them easier to work with in future.

Best Markdown Apps

As well as using Markdown in the Ghost editor, you might also want to use it in the formatting of your day-to-day documents. Lots of people enjoy writing in Markdown and then exporting later to HTML, PDF, or a wide variety of document types.

Here are some of our favourite Markdown editors for Mac, PC, desktop and mobile.

Mac OSX Markdown Editors

The Mac is graced with a large selection of Markdown apps to choose from! The very first one, Mou, is what the Ghost editor was originally based on.

• iA Writer - $19.99
• ByWord - $11.99
• Day One - $9.99
• SublimeText - $70

Windows PC Markdown Editors

Competition on Windows seems to be pretty sparse in the Markdown world, but most seem to agree that MarkdownPad is the tool of choice.

• WriteMonkey - Free
• MarkdownPad - Free + $14.99 Pro version

Apple iOS Markdown Apps

The best Markdown apps for iOS don't come cheap! On the plus side, most of them do offer extremely nice cloud-sync functionality which makes a big difference if you use the same app across multiple devices.

• Werdsmith - Free
• iA Writer - $9.99
• ByWord - $5.99
• Day One - $4.99

Google Android Markdown Apps

Markdown apps on the Google Play Store couldn't be any cheaper if they tried! This is just a small selection of a large number of apps that are out there. The quality seems to be decidedly lower overall than the iOS store, so it may take a little digging to find a good Android Markdown app.

• Jotterpad X - Free
• Writer - Free
• iA Writer - $5.99

Publishing Online with Markdown

Markdown based blogging is kind of what we specialise in! If you're looking for a blog with a comprehensive Markdown editor. Ghost might be exactly what you need for beautiful, simple publishing.

It works across any device, and any platform.

What to do next

After just a couple of hours with Markdown, we’re certain that your fingers will be flying across the keys as you pen your latest and greatest post.

Practice these steps to become a pro:

• Start with writing your first Markdown document and get a feel for the basics. It comes more quickly than you might think!
• Don't forget keyboard shortcuts for instant time-saving and much faster writing.
• Use HTML whenever you want advanced formatting, having this power available to you means you can really do (almost) anything.

We’ve been writing in Markdown for quite a while now, but we’re always learning new and amazing ways of using it. Got any tips that we’ve missed?

Foxes are red ↩︎

Dogs are usually not red ↩︎

Get notified when we ship new features.

You might also like....

TK reminders

✨ Emoji autocomplete ✨

Basic writing and formatting syntax

Create sophisticated formatting for your prose and code on GitHub with simple syntax.

In this article

To create a heading, add one to six # symbols before your heading text. The number of # you use will determine the hierarchy level and typeface size of the heading.

When you use two or more headings, GitHub automatically generates a table of contents that you can access by clicking within the file header. Each heading title is listed in the table of contents and you can click a title to navigate to the selected section.

Styling text

You can indicate emphasis with bold, italic, strikethrough, subscript, or superscript text in comment fields and .md files.

Quoting text

You can quote text with a > .

Quoted text is indented, with a different type color.

Note: When viewing a conversation, you can automatically quote text in a comment by highlighting the text, then typing R . You can quote an entire comment by clicking , then Quote reply . For more information about keyboard shortcuts, see " Keyboard shortcuts ."

Quoting code

You can call out code or a command within a sentence with single backticks. The text within the backticks will not be formatted. You can also press the Command + E (Mac) or Ctrl + E (Windows/Linux) keyboard shortcut to insert the backticks for a code block within a line of Markdown.

To format code or text into its own distinct block, use triple backticks.

For more information, see " Creating and highlighting code blocks ."

If you are frequently editing code snippets and tables, you may benefit from enabling a fixed-width font in all comment fields on GitHub. For more information, see " About writing and formatting on GitHub ."

Supported color models

In issues, pull requests, and discussions, you can call out colors within a sentence by using backticks. A supported color model within backticks will display a visualization of the color.

Here are the currently supported color models.

• A supported color model cannot have any leading or trailing spaces within the backticks.
• The visualization of the color is only supported in issues, pull requests, and discussions.

You can create an inline link by wrapping link text in brackets [ ] , and then wrapping the URL in parentheses ( ) . You can also use the keyboard shortcut Command + K to create a link. When you have text selected, you can paste a URL from your clipboard to automatically create a link from the selection.

You can also create a Markdown hyperlink by highlighting the text and using the keyboard shortcut Command + V . If you'd like to replace the text with the link, use the keyboard shortcut Command + Shift + V .

This site was built using [GitHub Pages](https://pages.github.com/).

Note: GitHub automatically creates links when valid URLs are written in a comment. For more information, see " Autolinked references and URLs ."

Section links

You can link directly to a section in a rendered file by hovering over the section heading to expose .

Relative links

You can define relative links and image paths in your rendered files to help readers navigate to other files in your repository.

A relative link is a link that is relative to the current file. For example, if you have a README file in root of your repository, and you have another file in docs/CONTRIBUTING.md , the relative link to CONTRIBUTING.md in your README might look like this:

GitHub will automatically transform your relative link or image path based on whatever branch you're currently on, so that the link or path always works. The path of the link will be relative to the current file. Links starting with / will be relative to the repository root. You can use all relative link operands, such as ./ and ../ .

Your link text should be on a single line. The example below will not work.

Relative links are easier for users who clone your repository. Absolute links may not work in clones of your repository - we recommend using relative links to refer to other files within your repository.

You can display an image by adding ! and wrapping the alt text in [ ] . Alt text is a short text equivalent of the information in the image. Then, wrap the link for the image in parentheses () .


GitHub supports embedding images into your issues, pull requests, discussions, comments and .md files. You can display an image from your repository, add a link to an online image, or upload an image. For more information, see " Uploading assets ."

Note: When you want to display an image that is in your repository, use relative links instead of absolute links.

Here are some examples for using relative links to display an image.

Note : The last two relative links in the table above will work for images in a private repository only if the viewer has at least read access to the private repository that contains these images.

For more information, see " Relative Links ."

Specifying the theme an image is shown to

You can specify the theme an image is displayed for in Markdown by using the HTML <picture> element in combination with the prefers-color-scheme media feature. We distinguish between light and dark color modes, so there are two options available. You can use these options to display images optimized for dark or light backgrounds. This is particularly helpful for transparent PNG images.

For example, the following code displays a sun image for light themes and a moon for dark themes:

The old method of specifying images based on the theme, by using a fragment appended to the URL ( #gh-dark-mode-only or #gh-light-mode-only ), is deprecated and will be removed in favor of the new method described above.

You can make an unordered list by preceding one or more lines of text with - , * , or + .

To order your list, precede each line with a number.

Nested Lists

You can create a nested list by indenting one or more list items below another item.

To create a nested list using the web editor on GitHub or a text editor that uses a monospaced font, like Visual Studio Code , you can align your list visually. Type space characters in front of your nested list item until the list marker character ( - or * ) lies directly below the first character of the text in the item above it.

Note : In the web-based editor, you can indent or dedent one or more lines of text by first highlighting the desired lines and then using Tab or Shift + Tab respectively.

To create a nested list in the comment editor on GitHub, which doesn't use a monospaced font, you can look at the list item immediately above the nested list and count the number of characters that appear before the content of the item. Then type that number of space characters in front of the nested list item.

In this example, you could add a nested list item under the list item 100. First list item by indenting the nested list item a minimum of five spaces, since there are five characters ( 100 . ) before First list item .

You can create multiple levels of nested lists using the same method. For example, because the first nested list item has seven characters ( ␣␣␣␣␣-␣ ) before the nested list content First nested list item , you would need to indent the second nested list item by at least two more characters (nine spaces minimum).

For more examples, see the GitHub Flavored Markdown Spec .

To create a task list, preface list items with a hyphen and space followed by [ ] . To mark a task as complete, use [x] .

If a task list item description begins with a parenthesis, you'll need to escape it with \ :

- [ ] \(Optional) Open a followup issue

For more information, see " About task lists ."

Mentioning people and teams

You can mention a person or team on GitHub by typing @ plus their username or team name. This will trigger a notification and bring their attention to the conversation. People will also receive a notification if you edit a comment to mention their username or team name. For more information about notifications, see " About notifications ."

Note: A person will only be notified about a mention if the person has read access to the repository and, if the repository is owned by an organization, the person is a member of the organization.

@github/support What do you think about these updates?

When you mention a parent team, members of its child teams also receive notifications, simplifying communication with multiple groups of people. For more information, see " About teams ."

Typing an @ symbol will bring up a list of people or teams on a project. The list filters as you type, so once you find the name of the person or team you are looking for, you can use the arrow keys to select it and press either tab or enter to complete the name. For teams, enter the @organization/team-name and all members of that team will get subscribed to the conversation.

The autocomplete results are restricted to repository collaborators and any other participants on the thread.

Referencing issues and pull requests

You can bring up a list of suggested issues and pull requests within the repository by typing # . Type the issue or pull request number or title to filter the list, and then press either tab or enter to complete the highlighted result.

For more information, see " Autolinked references and URLs ."

Referencing external resources

If custom autolink references are configured for a repository, then references to external resources, like a JIRA issue or Zendesk ticket, convert into shortened links. To know which autolinks are available in your repository, contact someone with admin permissions to the repository. For more information, see " Configuring autolinks to reference external resources ."

Uploading assets

You can upload assets like images by dragging and dropping, selecting from a file browser, or pasting. You can upload assets to issues, pull requests, comments, and .md files in your repository.

Using emojis

You can add emoji to your writing by typing :EMOJICODE: , a colon followed by the name of the emoji.

@octocat :+1: This PR looks great - it's ready to merge! :shipit:

Typing : will bring up a list of suggested emoji. The list will filter as you type, so once you find the emoji you're looking for, press Tab or Enter to complete the highlighted result.

For a full list of available emoji and codes, see the Emoji-Cheat-Sheet .

You can create a new paragraph by leaving a blank line between lines of text.

You can add footnotes to your content by using this bracket syntax:

The footnote will render like this:

Note : The position of a footnote in your Markdown does not influence where the footnote will be rendered. You can write a footnote right after your reference to the footnote, and the footnote will still render at the bottom of the Markdown.

Footnotes are not supported in wikis.

Alerts are a Markdown extension based on the blockquote syntax that you can use to emphasize critical information. On GitHub, they are displayed with distinctive colors and icons to indicate the significance of the content.

Use alerts only when they are crucial for user success and limit them to one or two per article to prevent overloading the reader. Additionally, you should avoid placing alerts consecutively. Alerts cannot be nested within other elements.

To add an alert, use a special blockquote line specifying the alert type, followed by the alert information in a standard blockquote. Five types of alerts are available:

Here are the rendered alerts:

Hiding content with comments

You can tell GitHub to hide content from the rendered Markdown by placing the content in an HTML comment.

Ignoring Markdown formatting

You can tell GitHub to ignore (or escape) Markdown formatting by using \ before the Markdown character.

Let's rename \*our-new-project\* to \*our-old-project\*.

For more information on backslashes, see Daring Fireball's " Markdown Syntax ."

Note : The Markdown formatting will not be ignored in the title of an issue or a pull request.

Disabling Markdown rendering

When viewing a Markdown file, you can click Code at the top of the file to disable Markdown rendering and view the file's source instead.

Disabling Markdown rendering enables you to use source view features, such as line linking, which is not possible when viewing rendered Markdown files.

Further reading

• GitHub Flavored Markdown Spec
• " About writing and formatting on GitHub "
• " Working with advanced formatting "
• " Quickstart for writing on GitHub "

How to use Markdown for writing technical documentation

Adobe technical documentation articles are written in a lightweight markup language called Markdown , which is both easy to read and easy to learn.

As we are storing Adobe Docs content in GitHub, it can use a version of Markdown called GitHub Flavored Markdown (GFM) , which provides additional functionality for common formatting needs. Additionally, Adobe extended Markdown in a few ways to support certain help-related features such as notes, tips, and embedded videos.

Markdown basics

The following sections describe the basics of authoring in Markdown.

To create a heading, use a hash mark (#) at the beginning of a line:

A paragraph requires no special syntax in Markdown.

To format text as bold , you enclose it in two asterisks. To format text as italic , you enclose it in a single asterisk:

To ignore Markdown formatting characters, use \ before the character:

Numbered lists and bullet lists

To create numbered lists, begin a line with 1. or 1) , but don’t use both formats within the same list. You don’t need to specify the numbers. GitHub does that for you.

• This is step 1.
• This is the next step.
• This is yet another step, the third.

To create bullet lists, begin a line with * or - or +, but don’t mix the formats within the same list. (Do not mix bullet formats, such as * and +, within the same document.)

• First item in an unordered list.
• Another item.
• Here we go  again.

You can also embed lists within lists and add content between list items.

Set up your table and code blocks.

Perform this step.

Make sure that your table looks like this:

This is the fourth step.

Do another step.

Tables are not part of the core Markdown specification, but Adobe supports them to an extent. Markdown doesn’t support multiple lines lists in cells. Best practice is to avoid using multiple lines in tables. You can create tables by using the pipe (|) character to delineate columns and rows. Hyphens create each column’s header, while pipes separate each column. Include a blank line before your table so it’s rendered correctly.

Simple tables work adequately in Markdown. However, tables that include multiple paragraphs or lists within a cell are difficult to work with. For such content, we recommend using a different format, such as headings & text.

For more information on creating tables, see:

• GitHub’s Organizing information with tables
• The Markdown Tables Generator web app
• Convert HTML tables to Markdown

The Markdown syntax for an inline link consists of the [link text] portion, which is the text that will be hyperlinked, followed by the (file-name.md) portion, which is the URL or file name that’s being linked to:

[link text](file-name.md)

For links to articles (cross-references) within the repository, use relative links. You can use all relative link operands, such as ./ (current directory), …/ (back one directory), and …/…/ (back two directories).

For more information on linking, see the Links article of this guide for linking syntax.

Code blocks

Markdown supports the placement of code blocks both inline in a sentence and as a separate “fenced” block between sentences. For details, see Markdown’s native support for code blocks

Use back ticks ( ` ) to create inline code styles within a paragraph. To create a specific multi-line code block, add three back ticks ( ``` ) before and after the code block (called a “fenced code block” in Markdown and just a “code block” component in AEM). For fenced code blocks, add the code language after the first set of back ticks so that Markdown correctly highlights code syntax. Example: ```javascript

This is inline code within a paragraph of text.

This is a fenced code block:

Custom Markdown extensions

Adobe articles use standard Markdown for most article formatting, such as paragraphs, links, lists, and headings. For richer formatting, articles can use extended Markdown features such as:

Note blocks

• Embedded videos
• Translation tags
• Component properties, such as assigning a different heading ID to a heading and specifying an image size

Use the Markdown block quote ( > ) at the beginning of every line to tie together an extended component, such as a note.

Some common Markdown elements such as headings and code blocks include extended properties. If you need to change default properties, add the parameters in french braces /{ /} after the component. Extended properties are described in context.

You can choose from these types of note blocks to draw attention to specific content:

• [!IMPORTANT]
• [!ADMINISTRATION]
• [!AVAILABILITY]
• [!PREREQUISITES]

In general, note blocks should be used sparingly because they can be disruptive. Although they also support code blocks, images, lists, and links, try to keep your note blocks simple and straightforward.

Embedded videos won’t natively render in Markdown, but you can use this Markdown extension.

https://video.tv.adobe.com/v/29770/?quality=12

More Like This

The “More Like This” component in AEM appears at the end of an article. It displays related links. When the article is rendered, it can be formatted the same as level-2 headings (##) without being added to the mini-TOC.

UICONTROL and DNL

All of our Markdown help content is localized using machine translation initially. If the help has never been localized, then we keep the machine translation. However, if the help content has been localized in the past, then the machine translated content will act as a placeholder while the content is in the process of human translation.

[!UICONTROL]

During machine translation, items tagged with [!UICONTROL] are checked against a localization database for the appropriate translation. In the case that the UI is not localized, this tag will allow the system to leave the UI reference in English for that particular language (ie. Analytics references in Italian).

Example source content:

As a rule, we use a “Do not translate” list to tell the machine translation engines what to keep in English. The most prevalent items would be the long solution names like “Adobe Analytics”, “Adobe Campaign”, and “Adobe Target”. However, there may be cases where we need to force the engine to use English because the term in question may be used in a specific or general way. This most obvious case would be short names for the solutions like “Analytics”, “Campaign”, “Target” etc. It would be difficult for a machine to understand that these are solution names and not general terms. The tag may also be used for third-party names/features which always remain in English or for shorter sections of text like a phrase or sentence which must remain in English.

Gotchas and troubleshooting

Alt text that contains underscores won’t be rendered properly. For example, instead of using this:

Our best practice is to use hyphens (-) instead of underscores (_) in filenames.

Apostrophes and quotation marks

If you copy text into a Markdown editor, the text might contain “smart” (curly) apostrophes or quotation marks. These need to be encoded or changed to basic apostrophes or quotation marks. Otherwise, you end up with odd characters like this when the file is published: It’s

Here are the encodings for the “smart” versions of these punctuation marks:

• Left (opening) quotation mark: &#8220;
• Right (closing) quotation mark: &#8221;
• Right (closing) single quotation mark or apostrophe: &#8217;
• Left (opening) single quotation mark (rarely used): &#8216;

Angle brackets

If you use angle brackets in text (not code) in your file–for example, to denote a placeholder–you need to manually encode the angle brackets. Otherwise, Markdown thinks that they’re intended to be an HTML tag.

For example, encode <script name> as &lt;script name&gt;

Ampersands in titles

Ampersands (&) aren’t allowed in titles. Use “and” instead, or use the &amp; encoding.

Markdown resources

• Introduction to Markdown
• GitHub’s Markdown Basics

• Getting Started
• Installation
• Writing Your Docs
• Choosing Your Theme
• Customizing Your Theme
• Localizing Your Theme
• Configuration
• Command Line Interface
• Deploying Your Docs
• Developer Guide
• Translations
• API Reference
• Release Notes
• Contributing
• Edit on GitHub
• File layout
• Writing with Markdown

Writing your docs 

How to layout and write your Markdown source files.

File layout 

Your documentation source should be written as regular Markdown files (see Writing with Markdown below), and placed in the documentation directory . By default, this directory will be named docs and will exist at the top level of your project, alongside the mkdocs.yml configuration file.

The simplest project you can create will look something like this:

By convention your project homepage should be named index.md (see Index pages below for details). Any of the following file extensions may be used for your Markdown source files: markdown , mdown , mkdn , mkd , md . All Markdown files included in your documentation directory will be rendered in the built site regardless of any settings.

Files and directories with names which begin with a dot (for example: .foo.md or .bar/baz.md ) are ignored by MkDocs. This can be overridden with the exclude_docs config .

You can also create multi-page documentation, by creating several Markdown files:

The file layout you use determines the URLs that are used for the generated pages. Given the above layout, pages would be generated for the following URLs:

You can also include your Markdown files in nested directories if that better suits your documentation layout.

Source files inside nested directories will cause pages to be generated with nested URLs, like so:

Any files which are not identified as Markdown files (by their file extension) within the documentation directory are copied by MkDocs to the built site unaltered. See how to link to images and media below for details.

Index pages 

When a directory is requested, by default, most web servers will return an index file (usually named index.html ) contained within that directory if one exists. For that reason, the homepage in all of the examples above has been named index.md , which MkDocs will render to index.html when building the site.

Many repository hosting sites provide special treatment for README files by displaying the contents of the README file when browsing the contents of a directory. Therefore, MkDocs will allow you to name your index pages as README.md instead of index.md . In that way, when users are browsing your source code, the repository host can display the index page of that directory as it is a README file. However, when MkDocs renders your site, the file will be renamed to index.html so that the server will serve it as a proper index file.

If both an index.md file and a README.md file are found in the same directory, then the index.md file is used and the README.md file is ignored.

Configure Pages and Navigation 

The nav configuration setting in your mkdocs.yml file defines which pages are included in the global site navigation menu as well as the structure of that menu. If not provided, the navigation will be automatically created by discovering all the Markdown files in the documentation directory . An automatically created navigation configuration will always be sorted alphanumerically by file name (except that index files will always be listed first within a sub-section). You will need to manually define your navigation configuration if you would like your navigation menu sorted differently.

A minimal navigation configuration could look like this:

All paths in the navigation configuration must be relative to the docs_dir configuration option. If that option is set to the default value, docs , the source files for the above configuration would be located at docs/index.md and docs/about.md .

The above example will result in two navigation items being created at the top level and with their titles inferred from the contents of the Markdown file or, if no title is defined within the file, of the file name. To override the title in the nav setting add a title right before the filename.

Note that if a title is defined for a page in the navigation, that title will be used throughout the site for that page and will override any title defined within the page itself.

Navigation sub-sections can be created by listing related pages together under a section title. For example:

With the above configuration we have three top level items: "Home", "User Guide" and "About." "Home" is a link to the homepage for the site. Under the "User Guide" section two pages are listed: "Writing your docs" and "Styling your docs." Under the "About" section two more pages are listed: "License" and "Release Notes."

Note that a section cannot have a page assigned to it. Sections are only containers for child pages and sub-sections. You may nest sections as deeply as you like. However, be careful that you don't make it too difficult for your users to navigate through the site navigation by over-complicating the nesting. While sections may mirror your directory structure, they do not have to.

Any pages not listed in your navigation configuration will still be rendered and included with the built site, however, they will not be linked from the global navigation and will not be included in the previous and next links. Such pages will be "hidden" unless linked to directly.

Writing with Markdown 

MkDocs pages must be authored in Markdown , a lightweight markup language which results in easy-to-read, easy-to-write plain text documents that can be converted to valid HTML documents in a predictable manner.

MkDocs uses the Python-Markdown library to render Markdown documents to HTML. Python-Markdown is almost completely compliant with the reference implementation , although there are a few very minor differences .

In addition to the base Markdown syntax which is common across all Markdown implementations, MkDocs includes support for extending the Markdown syntax with Python-Markdown extensions . See the MkDocs' markdown_extensions configuration setting for details on how to enable extensions.

MkDocs includes some extensions by default, which are highlighted below.

Internal links 

MkDocs allows you to interlink your documentation by using regular Markdown links . However, there are a few additional benefits to formatting those links specifically for MkDocs as outlined below.

Linking to pages 

When linking between pages in the documentation you can simply use the regular Markdown linking syntax, including the relative path to the Markdown document you wish to link to.

When the MkDocs build runs, these Markdown links will automatically be transformed into an HTML hyperlink to the appropriate HTML page.

Using absolute paths with links is not officially supported. Relative paths are adjusted by MkDocs to ensure they are always relative to the page. Absolute paths are not modified at all. This means that your links using absolute paths might work fine in your local environment but they might break once you deploy them to your production server.

If the target documentation file is in another directory you'll need to make sure to include any relative directory path in the link.

The toc extension is used by MkDocs to generate an ID for every header in your Markdown documents. You can use that ID to link to a section within a target document by using an anchor link. The generated HTML will correctly transform the path portion of the link, and leave the anchor portion intact.

Note that IDs are created from the text of a header. All text is converted to lowercase and any disallowed characters, including white-space, are converted to dashes. Consecutive dashes are then reduced to a single dash.

There are a few configuration settings provided by the toc extension which you can set in your mkdocs.yml configuration file to alter the default behavior:

Generate permanent links at the end of each header. Default: False .

When set to True the paragraph symbol (¶ or &para; ) is used as the link text. When set to a string, the provided string is used as the link text. For example, to use the hash symbol ( # ) instead, do:

Base level for headers. Default: 1 .

This setting allows the header levels to be automatically adjusted to fit within the hierarchy of your HTML templates. For example, if the Markdown text for a page should not contain any headers higher than level 2 ( <h2> ), do:

Then any headers in your document would be increased by 1. For example, the header # Header would be rendered as a level 2 header ( <h2> ) in the HTML output.

Word separator. Default: - .

Character which replaces white-space in generated IDs. If you prefer underscores, then do:

Note that if you would like to define multiple of the above settings, you must do so under a single toc entry in the markdown_extensions configuration option.

Linking to images and media 

As well as the Markdown source files, you can also include other file types in your documentation, which will be copied across when generating your documentation site. These might include images and other media.

For example, if your project documentation needed to include a GitHub Pages CNAME file and a PNG formatted screenshot image then your file layout might look as follows:

To include images in your documentation source files, simply use any of the regular Markdown image syntaxes:

Your image will now be embedded when you build the documentation, and should also be previewed if you're working on the documentation with a Markdown editor.

Linking from raw HTML 

Markdown allows document authors to fall back to raw HTML when the Markdown syntax does not meets the author's needs. MkDocs does not limit Markdown in this regard. However, as all raw HTML is ignored by the Markdown parser, MkDocs is not able to validate or convert links contained in raw HTML. When including internal links within raw HTML, you will need to manually format the link appropriately for the rendered document.

Meta-Data 

MkDocs includes support for both YAML and MultiMarkdown style meta-data (often called front-matter). Meta-data consists of a series of keywords and values defined at the beginning of a Markdown document, which are stripped from the document prior to it being processing by Python-Markdown. The key/value pairs are passed by MkDocs to the page template. Therefore, if a theme includes support, the values of any keys can be displayed on the page or used to control the page rendering. See your theme's documentation for information about which keys may be supported, if any.

In addition to displaying information in a template, MkDocs includes support for a few predefined meta-data keys which can alter the behavior of MkDocs for that specific page. The following keys are supported:

The template to use with the current page.

By default, MkDocs uses the main.html template of a theme to render Markdown pages. You can use the template meta-data key to define a different template file for that specific page. The template file must be available on the path(s) defined in the theme's environment.

The "title" to use for the document.

MkDocs will attempt to determine the title of a document in the following ways, in order:

A title defined in the nav configuration setting for a document.

A title defined in the title meta-data key of a document.

A level 1 Markdown header on the first line of the document body. ( Setext-style headers are supported only since MkDocs 1.5 .)

The filename of a document.

Upon finding a title for a page, MkDoc does not continue checking any additional sources in the above list.

YAML Style Meta-Data 

YAML style meta-data consists of YAML key/value pairs wrapped in YAML style delimiters to mark the start and/or end of the meta-data. The first line of a document must be --- . The meta-data ends at the first line containing an end deliminator (either --- or ... ). The content between the delimiters is parsed as YAML .

YAML is able to detect data types. Therefore, in the above example, the values of title , summary and some_url are strings, the value of authors is a list of strings and the value of date is a datetime.date object. Note that the YAML keys are case sensitive and MkDocs expects keys to be all lowercase. The top level of the YAML must be a collection of key/value pairs, which results in a Python dict being returned. If any other type is returned or the YAML parser encounters an error, then MkDocs does not recognize the section as meta-data, the page's meta attribute will be empty, and the section is not removed from the document.

MultiMarkdown Style Meta-Data 

MultiMarkdown style meta-data uses a format first introduced by the MultiMarkdown project. The data consists of a series of keywords and values defined at the beginning of a Markdown document, like this:

The keywords are case-insensitive and may consist of letters, numbers, underscores and dashes and must end with a colon. The values consist of anything following the colon on the line and may even be blank.

If a line is indented by 4 or more spaces, that line is assumed to be an additional line of the value for the previous keyword. A keyword may have as many lines as desired. All lines are joined into a single string.

The first blank line ends all meta-data for the document. Therefore, the first line of a document must not be blank.

MkDocs does not support YAML style delimiters ( --- or ... ) for MultiMarkdown style meta-data. In fact, MkDocs relies on the the presence or absence of the delimiters to determine whether YAML style meta-data or MultiMarkdown style meta-data is being used. If the delimiters are detected, but the content between the delimiters is not valid YAML meta-data, MkDocs does not attempt to parse the content as MultiMarkdown style meta-data.

The tables extension adds a basic table syntax to Markdown which is popular across multiple implementations. The syntax is rather simple and is generally only useful for simple tabular data.

A simple table looks like this:

If you wish, you can add a leading and tailing pipe to each line of the table:

Specify alignment for each column by adding colons to separator lines:

Note that table cells cannot contain any block level elements and cannot contain multiple lines of text. They can, however, include inline Markdown as defined in Markdown's syntax rules.

Additionally, a table must be surrounded by blank lines. There must be a blank line before and after the table.

Fenced code blocks 

The fenced code blocks extension adds an alternate method of defining code blocks without indentation.

The first line should contain 3 or more backtick ( ` ) characters, and the last line should contain the same number of backtick characters ( ` ):

With this approach, the language can optionally be specified on the first line after the backticks which informs any syntax highlighters of the language used:

Note that fenced code blocks can not be indented. Therefore, they cannot be nested inside list items, blockquotes, etc.

From here you can search these documents. Enter your search terms below.

Keyboard Shortcuts

R news and tutorials contributed by hundreds of R bloggers

Crafting elegant scientific documents in rstudio: a latex and r markdown tutorial.

Posted on April 11, 2024 by Numbers around us in R bloggers | 0 Comments

Introduction

In the world of scientific research and academic writing, the clarity, precision, and aesthetics of your documents can significantly impact their reception and comprehension. LaTeX, a powerful typesetting system, has long been revered for its ability to create beautifully formatted documents, especially those requiring complex mathematical expressions and detailed layouts. However, the steep learning curve associated with LaTeX can deter many. Enter R Markdown, a tool that simplifies the creation of dynamic documents, presentations, and reports directly from R code. When combined with the versatility of RStudio, it offers a more accessible entry point into the world of LaTeX, without sacrificing the depth and precision that professional documents require.

This tutorial aims to bridge the gap between the high-quality typesetting capabilities of LaTeX and the dynamic, code-integrated documentation of R Markdown. Whether you’re compiling research findings, drafting an academic paper, or preparing a report with rich data visualizations, integrating LaTeX with R Markdown in RStudio enhances both the appearance and functionality of your work. By the end of this guide, you’ll be equipped with the knowledge to leverage the best of both worlds, crafting documents that stand out for their elegance and precision.

Prerequisites and Setup

Installing rstudio and latex.

Before we dive into the intricacies of combining LaTeX with R Markdown, let’s ensure you have all the necessary tools installed. RStudio is an indispensable IDE for anyone working with R, and it provides seamless support for R Markdown. LaTeX, on the other hand, is a typesetting system that excels in document preparation, especially for those containing complex mathematical formulas.

• RStudio : If you haven’t already, download and install RStudio . Choose the version appropriate for your operating system.
• LaTeX Distribution : For LaTeX, you need a distribution based on your operating system. Windows users can opt for MiKTeX , macOS users for MacTeX , and Linux users for TeX Live . Installation links and instructions are readily available on their respective websites.

After installing both RStudio and your LaTeX distribution, ensure that RStudio can locate your LaTeX installation. This integration is typically automatic, but you can verify or adjust the settings in RStudio by navigating to Tools > Global Options > Sweave.

Configuring RStudio for LaTeX and R Markdown

With RStudio and LaTeX installed, the next step is to configure your RStudio environment for an optimal working experience. This involves:

• Installing Necessary R Packages : Open RStudio and install the rmarkdown package, which supports the integration of R code with Markdown (and by extension, LaTeX) for dynamic document generation. Install it by running:
• Testing Your Setup : To confirm everything is set up correctly, create a new R Markdown document. Go to File > New File > R Markdown… , then choose PDF as the output format. This action requires LaTeX for PDF generation, so if it succeeds without errors, your setup is correct.

This section’s goal is to ensure you have a smooth start with all the necessary tools at your disposal. Once you’re set up, the real fun begins: exploring the synergy between LaTeX and R Markdown to create stunning scientific documents.

Your First R Markdown Document with LaTeX

Creating your first R Markdown document integrated with LaTeX in RStudio is a simple yet exciting process. This section will guide you through creating a basic document, adding LaTeX for formatting and equations, and generating a PDF output.

Creating an R Markdown Document

• Start a New R Markdown File : In RStudio, go to File > New File > R Markdown… This opens a dialog where you can set the document’s title and output format. For now, select PDF and click OK.
• Explore the Default Content : RStudio will generate a sample document filled with some basic Markdown content and example code chunks. This template serves as an excellent introduction to R Markdown’s capabilities.

Integrating Basic LaTeX Elements

Within your R Markdown document, you can start integrating LaTeX directly. Here’s how you can add some basic LaTeX commands for text formatting and sections:

Adding Mathematical Expressions

One of LaTeX’s strengths is its ability to format complex mathematical expressions beautifully. In R Markdown, you can include these expressions by enclosing them in dollar signs for inline equations or double dollar signs for displayed equations:

Compiling to PDF

After adding your content, compile the document to PDF by clicking the “Knit” button in RStudio and selecting PDF. RStudio will use LaTeX to process your document, incorporating any LaTeX commands or mathematical expressions you’ve included, and generate a PDF.

This simple exercise demonstrates the power of combining R Markdown’s dynamic capabilities with LaTeX’s typesetting prowess, all within the RStudio environment. Whether you’re documenting research findings, drafting a paper, or preparing a report, this approach allows you to create professional, elegantly formatted documents efficiently.

Advanced LaTeX Features in R Markdown

Having grasped the basics of integrating LaTeX into R Markdown documents, we’ll now delve into advanced features to further elevate your scientific document’s quality. This segment highlights enhanced figure and table management, utilizing custom LaTeX commands, and effectively handling bibliographies within RStudio.

Working with Figures and Tables

LaTeX is renowned for its precise control over figures and tables, but in R Markdown, we approach these elements differently, leveraging Markdown and R code chunks for dynamic content integration and formatting.

For static images, use Markdown syntax:

For dynamically generated figures from R:

To create detailed and customizable tables in your R Markdown document using LaTeX, you’ll directly use the tabular environment provided by LaTeX. This allows for precise control over the table's appearance, alignment, and overall structure. Here's a basic example of creating a table with LaTeX:

This LaTeX code snippet places a table with headers aligned to the left, center, and right. The \hline command creates horizontal lines for clarity, and \textbf is used for bold header text. The \caption{} and \label{} commands are used for the table's caption and referencing it in the text, respectively.

Defining and Using Custom LaTeX Commands

You can define custom LaTeX commands for repetitive tasks or to simplify complex formatting. Custom commands are defined in the YAML header of your R Markdown document using header-includes:

This command, \highlight{}, makes specified text bold and red. To use this command within your document:

Applying Custom Commands in Tables

Your custom LaTeX commands can be utilized within tables to emphasize specific pieces of data or apply consistent formatting. Using the previously defined \highlight{} command:

This example shows how to apply the \highlight{} command within a table to make specific data stand out.

In this chapter, we’ve explored how to enhance your R Markdown documents with figures and sophisticated table formatting using LaTeX and the creation and application of custom LaTeX commands. Starting with the tabular environment, we demonstrated the method to craft detailed tables that meet specific aesthetic and structural requirements. Additionally, we covered how to define and utilize custom LaTeX commands within your document, allowing for efficient and consistent formatting across your scientific documents. This approach ensures that your work not only conveys information effectively but also adheres to the high standards of professional and academic presentation.

Crafting Complex Scientific Equations with LaTeX in R Markdown

The seamless integration of LaTeX within R Markdown particularly shines when dealing with complex scientific equations, which are cumbersome, if not impossible, to accurately represent in plain text or basic Markdown. LaTeX provides a comprehensive set of tools for typesetting mathematical expressions, from simple fractions to elaborate equations used in advanced physics and mathematics. This chapter demonstrates how to leverage LaTeX for this purpose within an R Markdown document.

Basic Mathematical Expressions

LaTeX allows for the inline and block display of mathematical expressions. For inline equations, enclose your LaTeX code in single dollar signs ($), and for equations that should be displayed as a separate block, use double dollar signs ($$).

Inline Equation :

Displayed Equation:

This displays the equation centered on its own line, making it stand out for emphasis.

Advanced Equation Formatting

LaTeX excels in formatting complex equations, such as systems of equations, matrices, and functions involving sums, integrals, and limits.

System of Equations :

These examples demonstrate just a fraction of the capabilities LaTeX offers for mathematical typesetting. When utilized within R Markdown, it enables authors to seamlessly integrate complex mathematical content into their documents, enhancing both readability and professionalism.

Utilizing LaTeX for Scientific Notation

Scientific documents often require notation that is difficult or awkward to express in other formats. LaTeX addresses this with a broad array of symbols and structures designed specifically for scientific writing:

The combination of R Markdown and LaTeX provides a powerful toolset for scientists, mathematicians, and anyone else working with complex equations or scientific notation. It brings together the best of both worlds: the dynamism and reproducibility of R Markdown with the precise typesetting and extensive capabilities of LaTeX.

Some more complex equations

Fourier Series:

Schrodinger equation:

General relativity field equation:

Navier-Stokes Equations for Fluid Dynamics:

And render of all equations included in chapter.

Compiling Documents and Customizing Outputs in R Markdown

R Markdown provides a seamless workflow for creating dynamic documents, reports, presentations, and more, directly from R. When incorporating LaTeX, you gain additional control over the document’s appearance, enabling the creation of professional-grade scientific documents. This chapter explores how to compile your R Markdown documents into PDFs, leveraging LaTeX for advanced formatting, and how to customize these outputs to fit various academic and professional standards.

Compiling R Markdown Documents to PDF

To compile an R Markdown document to PDF with LaTeX formatting:

• Ensure LaTeX is Installed: Before compiling, make sure you have a LaTeX distribution installed on your computer, as discussed in the setup chapter.
• Use the ‘Knit’ Button: In RStudio, the simplest way to compile your document is by using the Knit button. When you click Knit, RStudio automatically renders your document into a PDF, incorporating any LaTeX code or styling you’ve included.
• Customizing the Build Process: For more control over the compilation process, you can use the rmarkdown::render() function in the R console:

This function allows for additional arguments and customization, offering more flexibility than the Knit button.

Customizing PDF Output with LaTeX

LaTeX allows for extensive customization of PDF output through the use of packages and settings defined in the preamble of your R Markdown document. Here are a few ways to customize your PDF documents:

• Page Layout and Fonts : Use LaTeX packages such as geometry to adjust margins, fancyhdr for custom headers and footers, and fontspec for font customization.
• Section Formatting : Customize section titles using the titlesec package.
• Including External LaTeX Files : For complex documents, you might want to maintain your LaTeX preamble in a separate .tex file and include it in your R Markdown document.

Advanced Document Features

Leveraging LaTeX within R Markdown also allows for the inclusion of advanced document features that are typically challenging to implement, such as conditional text rendering, custom automatic numbering for figures and tables, and intricate mathematical typesetting, which we’ve covered in the previous chapter.

The combination of R Markdown and LaTeX offers unparalleled flexibility and power for scientific document creation. By mastering the compilation process and customizing the output, you can produce documents that not only meet the rigorous standards of academic and professional communication but also reflect your personal style and preferences.

Further Resources for Mastering LaTeX in R Markdown

Having explored the fundamentals and some advanced techniques for integrating LaTeX into R Markdown documents, it’s beneficial to know where to look for further information, tutorials, and community support to continue enhancing your skills. This final chapter provides a curated list of resources, including books, online tutorials, forums, and packages, designed to deepen your understanding and proficiency in using LaTeX with R Markdown for creating professional and sophisticated documents.

• “ R Markdown: The Definitive Guide ” by Yihui Xie, J.J. Allaire, and Garrett Grolemund. This comprehensive guide provides a thorough introduction to R Markdown, including its integration with LaTeX for producing high-quality documents.
• “ The LaTeX Companion ” by Frank Mittelbach and Michel Goossens. A detailed reference book for LaTeX users, covering a wide range of topics from basic document formatting to more complex customizations and extensions.
• “ Practical R Markdown ” by Benjamin Soltoff. This book focuses on the practical aspects of using R Markdown in research and data analysis, with sections dedicated to integrating LaTeX for academic writing.

Online Tutorials and Guides

• Overleaf’s LaTeX Tutorials : Overleaf offers a comprehensive series of tutorials for LaTeX beginners and advanced users alike, covering everything from basic document structure to complex mathematical typesetting.
• RStudio’s R Markdown Documentation : The official R Markdown website by RStudio provides extensive documentation, tutorials, and galleries of examples to help users harness the full potential of R Markdown, including its LaTeX capabilities.

Community Forums and Support

• Stack Exchange TeX — LaTeX Stack Exchange : A question and answer site for users of TeX, LaTeX, ConTeXt, and related typesetting systems. It’s an excellent resource for getting help with specific LaTeX questions or issues.
• RStudio Community : The RStudio Community forum is a great place to ask questions and share insights about using R Markdown and LaTeX.

Packages and Tools

• tinytex : An R package that provides a lightweight, portable, and easy-to-maintain LaTeX distribution. It’s specifically designed to simplify the management of LaTeX distributions in R Markdown workflows.
• LaTeX Workshop for Visual Studio Code : For users who prefer Visual Studio Code as their editor, this extension enhances the LaTeX experience with features like build automation, comprehensive linting, and preview.

While we’ve covered substantial ground in this guide, the journey to mastering LaTeX in R Markdown is ongoing. The resources listed in this chapter offer pathways to further exploration and mastery. Whether you’re looking to refine your document designs, tackle complex typesetting challenges, or simply stay updated on new packages and features, the LaTeX and R Markdown communities offer a wealth of knowledge and support.

Remember, the key to proficiency in LaTeX and R Markdown is practice and engagement with the community. Don’t hesitate to experiment with your documents, ask questions, and share your knowledge with others. With these resources at your disposal, you’re well-equipped to take your document creation skills to new heights.

Crafting Elegant Scientific Documents in RStudio: A LaTeX and R Markdown Tutorial was originally published in Numbers around us on Medium, where people are continuing the conversation by highlighting and responding to this story.

Copyright © 2024 | MH Corporate basic by MH Themes

Never miss an update! Subscribe to R-bloggers to receive e-mails with the latest R posts. (You will not see this message again.)

1. Introduction Last updated: 2021-11-14

The main idea of Writage is to provide the opportunity to write in Markdown to those who like to use Microsoft Word. There are lots of Markdown editors such as iA Writer, Texts, WriteMonkey or Byword and online Markdown writing services, like StackEdit, Dillinger or Markable for people who like to have a minimalistic, distraction-free interface. However there is nothing available for those who prefer to use the rich interface and features of Microsoft Word.

So Writage is designed for everyone who would like to start writing well-structured documents and doesn’t have time for or doesn’t want to dive into the details of Markdown syntax, or prefers to use Word as a text editor.

Writage enables Microsoft Word to create and edit Markdown files (with .md extension), as well as save your .docx files as Markdown files. It is also capable of copying selected rich-text as Markdown, and pasting Markdown as rich text.

2. Installation

The installation process is very simple and takes just a few minutes.

• Download the latest version of Writage on your computer from the Download section on our website.
• Double-click on file «Writage.msi» and follow the instructions. Please, note that you should have «Administrator» rights on your computer.
• Launch Microsoft Word and start writing in a new format.

Installation process:

Before starting installation, please, make sure that you have «Administrator» rights on your computer.

How to uninstall

We are sorry to hear that you are not going to use Writage in future, but if you need to uninstall Writage, you can do it in a few simple steps:

• Press the "Windows Key" on your keyboard.
• Open "Settings/Apps&Features" window.
• Click on «Writage» and follow the instructions.
• Writage plugin is uninstalled and no longer present on your computer.

3. How to use

Writage helps you to save your Word document as a Markdown file or your Markdown file as Microsoft Word document without any other converters.

Moreover, Writage turns Word into your Markdown WYSIWYG editor, so you will be able to open a Markdown file and edit it, like you normally edit any document in Microsoft Word.

3.1 Open Markdown file

On receiving a Markdown document from another person or downloading from the web, you don’t have to install any additional software to be able to render and read it as a normal document (without the distraction of formatting tags).

• Launch Microsoft Word.
• Choose «Open» command and select the Markdown document you would like to open. Or simply double-click on a Markdown file in File Explorer
• File will be shown in the Microsoft Word interface like any other document.

3.2 Convert Microsoft Word documents to Markdown

If you don’t like the idea of using Microsoft Word as a text editor, you could simply save any Word document which you receive from your colleague as a Markdown file and continue to work with your favorite Markdown tool.

• Create a document or open an existing DOCX file.
• Choose «Save as…» command and choose «Markdown» from «Save as type» field

3.3 Convert Markdown files to DOCX documents

To be able to use the rich formatting functions of Microsoft Word or simply to share your Markdown file with people who use Microsoft Word, you should convert a Markdown file into a Word document.

• Open an existing Markdown file.
• Choose «Save as…» command and choose «Word Document(*.docx)» from «Save as type» field

3.4 Using Markdown syntax

With Writage it is easy to start writing in Markdown format, zero knowledge of syntax is required and you don’t have to know what document styles are supported in Markdown.

Most of the supported Markdown styles are available through the Writage tab on the MS Word ribbon. So all you need is to apply a style to selected text or insert an image or a table like you usually do when writing documents.

You can open the "Welcome.md" document at any time, by pressing the "Welcome" button on the ribbon, and see what different styles look like. Moreover you can save it somewhere on your disc and have some practice with editing a Markdown document using Microsoft Word.

3.5 Paste Markdown from clipboard

If you need to paste some text from Markdown syntax into a Microsoft Word document, using a simple "Copy/Paste" action, it can be easily done by Writage. The text will be displayed as it was predefined in source syntax.

To be able to paste raw Markdown code into a DOCX file you need to:

• Copy Markdown code into the clipboard by selecting the code and using the "Copy" button from the Context menu.
• Launch Microsoft Word and open your file.
• Press "Paste Markdown" button on "Writage" tab.
• You will see your selected text pasted into your document with all the predefined styles applied.

3.6 Copy Markdown to clipboard

In case you need to copy selected text from Microsoft Word into a Markdown document, please, follow the instructions below. The text will be inserted in CommonMark syntax.

• Copy selected text from your Microsoft Word document by making a selection and using the "Copy Markdown" button on the Writage tab
• Open your Markdown document.
• Use "Paste" command from the Context menu
• You will see the text from the Microsoft Word document pasted into your Markdown file with all the syntax.

3.7 Convert Markdown file to PDF

If you need to convert your Markdown files to PDF format, use Writage to open them in Microsoft Word and simply export them as PDF-files, using the standard Microsoft Word feature.

• Open your Markdown file in Microsoft Word
• Use "File/Export" command and follow the instructions.

3.8 Custom document styles

All you need to do is to create a new custom styles set with all the necessary changes in styles.

How to create a custom styles set:

• Launch Microsoft Word and open "Welcome.md" by pressing the "Welcome" button in Writage tab. This document contains all the styles,used by Writage for Markdown documents.

• Make all the necessary changes in styles, then open the "Design" tab and press the dropdown button in the bottom right corner.

• In the opened dialog box choose “Save as a New Style Set” option.

• The "Save as a New Style Set" dialog window will appear, please save the new style set as "Writage" and press the "Save" button.

• After that the created "Writage" style set will appear in the list of all the Style Sets in the "Custom" section.

• All the Markdown documents will be opened with the created "Writage" style set.

How to delete a custom styles set:

If you decide to come back to default Writage styles, please delete the custom "Writage" style set:

• Open the "Design" tab and choose the "Writage" style set in the "Custom" section.
• Open the context menu, using the mouse right-click and choose the "Delete" command.

• Confirm your choice by pressing the "Yes" button.
• After that the "Writage" style set will disappear in the list of all the Style Sets in the "Custom" section.
• All the Markdown documents will be opened with the default styles.

3.9 Settings

Writage implements the CommonMark standard syntax. However there are many Markdown syntax variations available and there are many different software products with different syntax requirements. In order to comply with them and integrate Writage smoothly into your workflow, you can use customized settings for paragraphs and lists.

You can find these settings by pressing the "Settings" button on the "Writage" tab (see picture above)

Paragraph Options

By default Writage inserts soft breaks at 80 characters when converting DOCX documents to Markdown format. It makes your content more comprehensible, because it is much easier to understand shorter fragments of text.

If you prefer to avoid that and to keep you paragraphs as a single line, please select the "Keep paragraph on single line" option (see picture above).

List Options

Writage inserts empty lines between elements of both types of lists: ordered and unordered. It makes a difference when you have lists with multiple paragraphs inside the single list item and lists with items which contain just one line of text. These empty lines will keep your lists look similar.

Writage inserts empty lines between elements of both types of lists: ordered and unordered. Without these extra lines lists with multiple paragraphs inside the single list item, and lists with items which contain just one line of text, will look different.

In case you would like to get rid of empty lines, please select the "No empty lines between list items" option (see picture above).

Code Block options

Code blocks in Markdown may be formatted with three tildes ( ~~~ ) symbols or three backticks ( ``` ). It is based on the Markdown syntax you use or the current settings of your Markdown editor or processor.

Writage by default formats Code block with backticks. In case you would like to use tildes, please select the "Format with tildes (~~~). You can change it back to backticks at any time.

Media Options

Writage stores all the document's images in the "media" folder located inside the same folder where your document is kept. If your workflow process requires a different name for the images folder, you can change it using the "Media Options" (see picture below).

4. Supported syntax

Writage utilises CommonMark as it is a widely used and very well documented Markdown syntax, which was adopted by: Discourse, GitHub, GitLab, Reddit, Stack Overflow and many more.

In addition to the standard CommonMark syntax, Writage provides support for tables (using GitHub Flavored Markdown syntax) and footnotes, which are common in scientific documents.

4.1 CommonMark standard syntax

In the table below you can see CommonMark standard syntax elements and how they will be appear in a Microsoft Word document and Markdown raw code.

You can use as many heading styles in your documents as needed. In the table above only Heading1 - Heading3 are shown to give you an idea of what headings look like in Markdown documents.

4.2 Extended Syntax

In the table below you can see the Extended Syntax used by Writage for tables and footnotes and how those elements will appear in a Microsoft Word document and Markdown raw code.

5. Resources

On this page we have published links on some useful resources to help you get started using Markdown in no time.

• Markdown on Wikipedia
• CommonMark syntax description
• GitHub Flavoured Markdown guide

In this section you can find a collection of frequently encountered questions.

6.1 Installation

Is there a version available for mac os.

The current version of Writage is for Windows users only. However we are exploring the possibility to make Writage available for Mac OS users.

Does Writage support Office 365?

Yes, Writage support Office 365, as well as 2010/2013/2016/2019.

I can't install Writage, what's wrong?

Please, make sure that you have «Administrator» rights on your computer.

6.2 Licensing

What's the difference between a personal and commercial license.

Personal license is intended for individual use. Therefore only one licence per user is available and the license will be issued on your own name.

Commercial license is designated for companies. The license will be issued on your company name, not on the name of an individual user. There is an option to purchase as many licenses as your company needs.

Can I use Writage on more than one computer?

Yes, you can use your licence on multiple computers (at home, at University, school, etc) as long as you have a license valid for the person who uses Writage and not someone else.

Can I buy a licence for my team?

If you are purchasing a licence for more than one person, you need to choose the Commercial licence at check-out.

6.3 Pricing

How do you process orders.

All our orders are processed by FastSpring. FastSpring is a well-known company that has been offering a full service e-commerce platform for companies that sell software since 2005.

How can I change the number of licences?

If you are going to buy some licenses for commercial use, you can enter the quantity you need on the checkout page. If you are going to buy a licence for your personal use, there will be only one licence available.

I bought a license, how to activate it?

In order to activate your license, please open the "Writage" tab in Microsoft Word, press "License" button and paste your license code into the dialog box.

I lost my licence, what to do?

If you lost your licence, please send us an email and we will resend you the licence code.

New Vatican document lists ‘grave violations’ of human dignity

By Andrea Tornielli

Three chapters offer the foundations for the fourth, which is dedicated to "some grave violations of human dignity".

That’s the structure of the Dicastery for the Doctrine of the Faith’s new Declaration Dignitas infinita , which commemorates the 75th anniversary of the Universal Declaration of Human Rights and reaffirms "the indispensable nature of the dignity of the human person in Christian anthropology " (Intro.)

The main novelty of the document, which is the fruit of five years' work, is the inclusion of a number of key themes from the recent papal magisterium that accompany the bioethical ones. In the 'non-exhaustive' list that is offered, abortion, euthanasia and surrogate motherhood are listed as violations of human dignity alongside war, poverty and human trafficking.

The new text thus contributes to overcoming the dichotomy that exists between those who focus exclusively on beginning-and-end-of-life issues, while forgetting so many other attacks against human dignity and, conversely, those who focus only on defending the poor and migrants while forgetting that life must be defended from conception to its natural conclusion.

Fundamental Principles

The first three parts of the Declaration recall fundamental principles.

"In the light of Revelation, the Church resolutely reiterates and confirms" the "ontological dignity of the human person, created in the image and likeness of God and redeemed in Jesus Christ" (1).

This is an "inalienable dignity”, corresponding to "human nature apart from all cultural change"(6). It is a "gift" and therefore present in "an unborn child, an unconscious person, or an older person in distress (9).

"The Church proclaims the equal dignity of all people, regardless of their living conditions or qualities" (17), and she does so on the basis of biblical revelation: women and men are created in the image of God.

Christ, by becoming incarnate, "confirmed the dignity of the body and soul" (19), and, in His rising, revealed to us that man's dignity man rests “above all on the fact that he is called to communion with God" (20).

The dignity of every person

The document highlights the misunderstandings of those who prefer the expression "personal dignity" to "human dignity", “since they understand a person to be only ‘one who is capable of reasoning’" (24).

Thus, according to them, "the unborn child would not have personal dignity, nor would the older person who is dependent upon others, nor would an individual with mental disabilities. On the contrary, the Church insists that the dignity of every human person, precisely because it is intrinsic, remains in all circumstances" (24).

Furthermore, the document stresses that "the concept of human dignity is also occasionally misused to justify an arbitrary proliferation of new rights … as if the ability to express and realize every individual preference or subjective desire should be guaranteed." (25).

The list of violations

The Declaration then presents the list of "some grave violations of human dignity".

This includes "all offences against life itself, such as murder, genocide, abortion, euthanasia, and willful suicide” must be recognized as contrary to human dignity ", but also "all violations of the integrity of the human person, such as mutilation, physical and mental torture, undue psychological pressures ".

And, finally, it includes "all offences against human dignity, such as subhuman living conditions, arbitrary imprisonment, deportation, slavery, prostitution, the selling of women and children, degrading working conditions where individuals are treated as mere tools for profit rather than free and responsible persons".

The death penalty is also cited, since it "violates the inalienable dignity of every person, regardless of the circumstances" (34).

Poverty, war and human trafficking

The first issue mentioned is poverty, "one of the greatest injustices in the contemporary world" (36).

Then there is war, "another tragedy that denies human dignity", and always a “defeat of humanity" (38), to the point that "it is very difficult nowadays to invoke the rational criteria elaborated in earlier centuries to speak of the possibility of a ‘just war.’"(39).

The Declaration also discusses the "travail of migrants", whose "lives are put at risk because they no longer have the means to start a family, to work, or to feed themselves" (40).

The document then dwells on "human trafficking", which is taking on "tragic dimensions" and is described as " vile activity, a disgrace to our societies that claim to be civilized ". The Declaration invites "exploiters and clients" to make a serious examination of conscience (41).

Similarly, it calls for the fight against phenomena such as “the marketing of human organs and tissues, the sexual exploitation of boys and girls, slave labour, including prostitution, the drug and weapons trade, terrorism, and international organized crime” (42). The document also mentions sexual abuse, which leaves “deep scars in the hearts of those who suffer it”: these are “sufferings that can last a lifetime and that no repentance can remedy” (43). Discrimination and violence against women are then discussed. Among the latter are listed "coercive abortions, which affect both mother and child, often to satisfy the selfishness of males" and "the practice of polygamy" (45). Femicide is also condemned (46).

Abortion and surrogacy

The condemnation of abortion is strong: "Among all the crimes which can be committed against life, procured abortion has characteristics making it particularly serious and deplorable", and reference is made to the fact that "defence of unborn life is closely linked to the defence of each and every other human right" (47).

The Declaration’s rejection of surrogacy, by means of which "the immensely worthy child becomes a mere object", is also strong. This is a practice that "represents a grave violation of the dignity of the woman and the child …  A child is always a gift and never the basis of a commercial contract.” (48)

The list goes on to mention euthanasia and assisted suicide, confusingly defined by some laws as " death with dignity". The document stresses that "suffering does not cause the sick to lose their dignity, which is intrinsically and inalienably their own" (51).

The Declaration then speaks of the importance of palliative care and the avoidance of “aggressive treatments or disproportionate medical procedures”, reaffirming that “Life is a right, not death, which must be welcomed, not administered” (52).

A further serious violation of human dignity is the marginalization of differently-abled persons (53).

Gender theory

The document begins the section on this topic by stressing that "every sign of unjust discrimination” against homosexual persons “is to be carefully avoided, particularly any form of aggression and violence".

It is “contrary to human dignity", the Declaration says, that in some places “not a few people are “imprisoned, tortured and even deprived of the good of life solely because of their sexual orientation" (55). Gender theory, which is “extremely dangerous since it cancels differences in its claim to make everyone equal", is then criticised (56).

The Church, we read, recalls that "human life in all its dimensions, both physical and spiritual, is a gift from God. This gift is to be accepted with gratitude and placed at the service of the good. Desiring a personal self-determination, as gender theory prescribes … amounts to a concession to the age-old temptation to make oneself God" (57).

Gender theory "intends to deny the greatest possible difference that exists between living beings: sexual difference” (58).

Therefore, " all attempts to obscure reference to the ineliminable sexual difference between man and woman” are “to be rejected" (59). Sex change is also judged negatively since it "risks threatening the unique dignity the person has received from the moment of conception". This does not mean, however, excluding the possibility that “a person with genital abnormalities that are already evident at birth or that develop later may choose to receive the assistance of healthcare professionals to resolve these abnormalities" (60).

Digital violence

The final item on the list is “digital violence”. “New forms of violence are spreading through social media”, we read, such as cyberbullying, and “the internet is also a channel for spreading pornography and the exploitation of persons for sexual purposes or through gambling” (61).

The Declaration ends by urging that “respect for the dignity of the human person beyond all circumstances be placed at the centre of the commitment to the common good and at the centre of every legal system” (64).

You can find the full text of the Declaration  Dignitas infinita  on the Holy See website .

Thank you for reading our article. You can keep up-to-date by subscribing to our daily newsletter. Just click here

More upcoming events:

Listen to our podcasts

Subscribe to our newsletters

To get the latest news

Regina Coeli

Papal audiences

Daily readings

Saint of the day

Get started with the latest updates for Dockerfile syntax (v1.7.0)

Tonis Tiigi

Dockerfiles are fundamental tools for developers working with Docker, serving as a blueprint for creating Docker images. These text documents contain all the commands a user could call on the command line to assemble an image. Understanding and effectively utilizing Dockerfiles can significantly streamline the development process, allowing for the automation of image creation and ensuring consistent environments across different stages of development. Dockerfiles are pivotal in defining project environments, dependencies, and the configuration of applications within Docker containers.

With new versions of the BuildKit builder toolkit , Docker Buildx CLI , and Dockerfile frontend for BuildKit (v1.7.0) , developers now have access to enhanced Dockerfile capabilities. This blog post delves into these new Dockerfile capabilities and explains how you can can leverage them in your projects to further optimize your Docker workflows.

Before we get started, here’s a quick reminder of how Dockerfile is versioned and what you should do to update it. 

Although most projects use Dockerfiles to build images, BuildKit is not limited only to that format. BuildKit supports multiple different frontends for defining the build steps for BuildKit to process. Anyone can create these frontends, package them as regular container images, and load them from a registry when you invoke the build.

With the new release, we have published two such images to Docker Hub : docker/dockerfile:1.7.0 and docker/dockerfile:1.7.0-labs .

To use these frontends, you need to specify a #syntax directive at the beginning of the file to tell BuildKit which frontend image to use for the build. Here we have set it to use the latest of the 1.x.x major version. For example:

This means that BuildKit is decoupled from the Dockerfile frontend syntax. You can start using new Dockerfile features right away without worrying about which BuildKit version you’re using. All the examples described in this article will work with any version of Docker that supports BuildKit ( the default builder as of Docker 23 ), as long as you define the correct #syntax directive on the top of your Dockerfile.

You can learn more about Dockerfile frontend versions in the documentation. 

Variable expansions

When you write Dockerfiles, build steps can contain variables that are defined using the build arguments ( ARG ) and environment variables ( ENV ) instructions. The difference between build arguments and environment variables is that environment variables are kept in the resulting image and persist when a container is created from it.

When you use such variables, you most likely use ${NAME} or, more simply, $NAME in COPY , RUN , and other commands.

You might not know that Dockerfile supports two forms of Bash-like variable expansion:

• ${variable:-word}: Sets a value to word if the variable is unset
• ${variable:+word}: Sets a value to word if the variable is set

Up to this point, these special forms were not that useful in Dockerfiles because the default value of ARG instructions can be set directly:

If you are an expert in various shell applications, you know that Bash and other tools usually have many additional forms of variable expansion to ease the development of your scripts.

In Dockerfile v1.7, we have added:

• ${variable#pattern} and ${variable##pattern} to remove the shortest or longest prefix from the variable’s value.
• ${variable%pattern} and ${variable%%pattern} to remove the shortest or longest suffix from the variable’s value.
• ${variable/pattern/replacement} to first replace occurrence of a pattern
• ${variable//pattern/replacement} to replace all occurrences of a pattern

How these rules are used might not be completely obvious at first. So, let’s look at a few examples seen in actual Dockerfiles.

For example, projects often can’t agree on whether versions for downloading your dependencies should have a “ v ” prefix or not. The following allows you to get the format you need:

In the next example, multiple variants are used by the same project:

To configure different command behaviors for multi-platform builds, BuildKit provides useful built-in variables like TARGETOS and TARGETARCH . Unfortunately, not all projects use the same values. For example, in containers and the Go ecosystem, we refer to 64-bit ARM architecture as arm64 , but sometimes you need aarch64 instead.

In this case, the URL also uses a custom name for AMD64 architecture. To pass a variable through multiple expansions, use another ARG definition with an expansion from the previous value. You could also write all the definitions on a single line, as ARG allows multiple parameters, which may hurt readability.

Note that the example above is written in a way that if a user passes their own --build-arg ARCH=value , then that value is used as-is.

Now, let’s look at how new expansions can be useful in multi-stage builds.

One of the techniques described in “Advanced multi-stage build patterns” shows how build arguments can be used so that different Dockerfile commands run depending on the build-arg value. For example, you can use that pattern if you build a multi-platform image and want to run additional COPY or RUN commands only for specific platforms. If this method is new to you, you can learn more about it from that post .

In summarized form, the idea is to define a global build argument and then define build stages that use the build argument value in the stage name while pointing to the base of your target stage via the build-arg name.

Old example:

When using this pattern for multi-platform builds, one of the limitations is that all the possible values for the build-arg need to be defined by your Dockerfile. This is problematic as we want Dockerfile to be built in a way that it can build on any platform and not limit it to a specific set. 

You can see other examples here and here of Dockerfiles where dummy stage aliases must be defined for all architectures, and no other architecture can be built. Instead, the pattern we would like to use is that there is one architecture that has a special behavior, and everything else shares another common behavior.

With new expansions, we can write this to demonstrate running special commands only on RISC-V, which is still somewhat new and may need custom behavior:

Let’s look at these ARCH definitions more closely.

• The first sets ARCH to TARGETARCH but removes riscv64 from the value.
• Next, as we described previously, we don’t actually want the other architectures to use their own values but instead want them all to share a common value. So, we set ARCH to common except if it was cleared from the previous riscv64 rule. 
• Now, if we still have an empty value, we default it back to $TARGETARCH .
• The last definition is optional, as we would already have a unique value for both cases, but it makes the final stage name base-riscv64 nicer to read.

Additional examples of including multiple conditions with shared conditions, or conditions based on architecture variants can be found in this GitHub Gist page.

Comparing this example to the initial example of conditions between stages, the new pattern isn’t limited to just controlling the platform differences of your builds but can be used with any build-arg. If you have used this pattern before, then you can effectively now define an “else” clause, whereas previously, you were limited to only “if” clauses.

Copy with keeping parent directories

The following feature has been released in the “labs” channel. Define the following at the top of your Dockerfile to use this feature.

When you are copying files in your Dockerfile, for example, do this:

This example means the source file is copied directly to the destination directory. If your source path was a directory, all the files inside that directory would be copied directly to the destination path.

What if you have a file structure like the following:

You want to copy only files in app1/src , but so that the final files at the destination would be /to/dest/dir/app1/src/server.go and not just /to/dest/dir/server.go .

With the new COPY --parents flag, you can write:

This will copy the files inside the src directory and recreate the app1/src directory structure for these files.

Things get more powerful when you start to use wildcard paths. To copy the src directories for both apps into their respective locations, you can write:

This will create both /to/dest/dir/app1 and /to/dest/dir/app2 , but it will not copy the docs directory. Previously, this kind of copy was not possible with a single command. You would have needed multiple copies for individual files (as shown in this example ) or used some workaround with the RUN --mount instruction instead.

You can also use double-star wildcard ( ** ) to match files under any directory structure. For example, to copy only the Go source code files anywhere in your build context, you can write:

If you are thinking about why you would need to copy specific files instead of just using COPY ./ to copy all files, remember that your build cache gets invalidated when you include new files in your build. If you copy all files, the cache gets invalidated when any file is added or changed, whereas if you copy only Go files, only changes in these files influence the cache.

The new --parents flag is not only for COPY instructions from your build context, but obviously, you can also use them in multi-stage builds when copying files between stages using COPY --from . 

Note that with COPY --from syntax, all source paths are expected to be absolute, meaning that if the --parents flag is used with such paths, they will be fully replicated as they were in the source stage. That may not always be desirable, and instead, you may want to keep some parents but discard and replace others. In that case, you can use a special /./ relative pivot point in your source path to mark which parents you wish to copy and which should be ignored. This special path component resembles how rsync works with the --relative flag.

This example above shows how only bin directories are copied from the collection of files that the intermediate stage generated, but all the directories will keep their paths relative to the out directory. 

Exclusion filters

The following feature has been released in the “labs” channel. Define the following at the top of your Dockerfile to use this feature:

Another related case when moving files in your Dockerfile with COPY and ADD instructions is when you want to move a group of files but exclude a specific subset. Previously, your only options were to use RUN --mount or try to define your excluded files inside a .dockerignore file. 

.dockerignore files, however, are not a good solution for this problem, because they only list the files excluded from the client-side build context and not from builds from remote Git/HTTP URLs and are limited to one per Dockerfile . You should use them similarly to .gitignore to mark files that are never part of your project but not as a way to define your application-specific build logic.

With the new --exclude=[pattern] flag, you can now define such exclusion filters for your COPY and ADD commands directly in the Dockerfile. The pattern uses the same format as .dockerignore .

The following example copies all the files in a directory except Markdown files:

You can use the flag multiple times to add multiple filters. The next example excludes Markdown files and also a file called README :

Double-star wildcards exclude not only Markdown files in the copied directory but also in any subdirectory:

As in .dockerignore files, you can also define exceptions to the exclusions with ! prefix. The following example excludes all Markdown files in any copied directory, except if the file is called important.md — in that case, it is still copied.

This double negative may be confusing initially, but note that this is a reversal of the previous exclude rule, and “include patterns” are defined by the source parameter of the COPY instruction.

When using --exclude together with previously described --parents copy mode, note that the exclude patterns are relative to the copied parent directories or to the pivot point /./ if one is defined. See the following directory structure for example:

This command would create the directory structure below. Note that only directories with the icons prefix were copied, the root parent directory assets was skipped as it was before the relative pivot point, and additionally, testapp was not copied as it was defined with an exclusion filter.

We hope this post gave you ideas for improving your Dockerfiles and that the patterns shown here will help you describe your build more efficiently. Remember that your Dockerfile can start using all these features today by defining the #syntax line on top, even if you haven’t updated to the latest Docker yet.

For a full list of other features in the new BuildKit, Buildx, and Dockerfile releases, check out the changelogs:

• BuildKit v0.13.0
• Buildx v0.13.0
• Dockerfile v1.7.0 v1.7.0-labs

Thanks to community members @tstenner , @DYefimov , and @leandrosansilva for helping to implement these features!

If you have issues or suggestions you want to share, let us know in the issue tracker.

• Subscribe to the Docker Newsletter .
• Get the latest release of Docker Desktop .
• Vote on what’s next! Check out our public roadmap .
• Have questions? The Docker community is here to help .
• New to Docker? Get started .

0 thoughts on "Get started with the latest updates for Dockerfile syntax (v1.7.0)"

Next-Level Error Handling: How Docker Desktop 4.29 Aims to Simplify Developer Challenges

Docker desktop 4.29: docker socket mount permissions in eci, advanced error management, moby 26, and new beta features , debian’s dedication to security: a robust foundation for docker developers.

Apr 9, 2024

• Engineering

• Election 2024
• Entertainment
• Newsletters
• Photography
• Personal Finance
• AP Investigations
• AP Buyline Personal Finance
• Press Releases
• Israel-Hamas War
• Russia-Ukraine War
• Global elections
• Asia Pacific
• Latin America
• Middle East
• Election Results
• Delegate Tracker
• AP & Elections
• March Madness
• AP Top 25 Poll
• Movie reviews
• Book reviews
• Personal finance
• Financial Markets
• Business Highlights
• Financial wellness
• Artificial Intelligence
• Social Media

Vatican blasts gender-affirming surgery, surrogacy and gender theory as violations of human dignity

The Vatican has declared that gender-affirming surgeries and surrogacy are grave violations of human dignity. A new document from the doctrine office puts them on a par with abortion and euthanasia as practices that violate God’s plan for human life. In its most eagerly anticipated section, the Vatican flat-out rejected “gender theory” or the idea that one’s gender can be changed.

The Vatican on Monday declared gender-affirming surgery and surrogacy as grave violations of human dignity, putting them on par with abortion and euthanasia as practices that reject God’s plan for human life. The Vatican’s doctrine office issued “Infinite Dignity,” a 20-page declaration that has been in the works for five years. After substantial revision in recent months, it was approved March 25 by Pope Francis, who ordered its publication.

The prefect of the Vatican’s Dicastery for the Doctrine of the Faith, Cardinal Victor Manuel Fernandez, presents the declaration ‘Dignitas Infinita’ (Infinite Dignity) during a press conference at the Vatican, Monday, April 8, 2024. (AP Photo/Gregorio Borgia)

• Copy Link copied

A copy of the 20-page “Infinite Dignity” declaration issued by the Vatican’s doctrine office sits on a journalist desk as the prefect of the Vatican’s Dicastery for the Doctrine of the Faith, Cardinal Victor Manuel Fernandez, meets the journalists during a press conference at the Vatican, Monday, April 8, 2024. (AP Photo/Gregorio Borgia)

VATICAN CITY (AP) — The Vatican on Monday declared gender-affirming surgery and surrogacy as grave violations of human dignity , putting them on par with abortion and euthanasia as practices that it said reject God’s plan for human life.

The Vatican’s doctrine office issued “Infinite Dignity,” a 20-page declaration that has been in the works for five years. After substantial revision in recent months, it was approved March 25 by Pope Francis, who ordered its publication.

From a pope who has made outreach to the LGBTQ+ community a hallmark of his papacy, the document was received as a setback, albeit predictable, by trans Catholics. But its message was also consistent with the Argentine Jesuit’s long-standing belief that while trans people should be welcomed in the church, so-called “gender ideologies” should not.

In its most eagerly anticipated section, the Vatican repeated its rejection of “gender theory,” or the idea that one’s biological sex can change. It said God created man and woman as biologically different, separate beings, and said people must not tinker with that or try to “make oneself God.”

“It follows that any sex-change intervention, as a rule, risks threatening the unique dignity the person has received from the moment of conception,” the document said.

It distinguished between gender-affirming surgeries, which it rejected, and “genital abnormalities” that are present at birth or that develop later. Those abnormalities can be “resolved” with the help of health care professionals, it said.

Advocates for LGBTQ+ Catholics immediately criticized the document as outdated, harmful and contrary to the stated goal of recognizing the “infinite dignity” of all of God’s children. They warned it could have real-world effects on trans people, fueling anti-trans violence and discrimination.

“While it lays out a wonderful rationale for why each human being, regardless of condition in life, must be respected, honored, and loved, it does not apply this principle to gender-diverse people,” said Francis DeBernardo of New Ways Ministry, which advocates for LGBTQ+ Catholics.

“It needs to be emphasized that biological sex and the sociocultural role of sex (gender) can be distinguished but not separated”

Nicolete Burbach, lead expert in social and environmental justice at the London Jesuit Centre, said the document showed the Vatican continues to fail to engage with queer and feminist approaches to the body “which it simply dismisses as supposedly subjecting both the body and human dignity itself to human whims.”

“I think the main difficulty faced by the document is that it attempts to affirm the church’s authentic commitment to human dignity in the face of a troubling history on the part of the church itself around attacks on that dignity,” said Burbach, a trans Catholic theologian who researches transness and the Catholic Church.

The document’s existence, rumored since 2019, was confirmed in recent weeks by the new prefect of the Dicastery for the Doctrine of the Faith, Argentine Cardinal Víctor Manuel Fernández, a close Francis confidant.

Fernández had cast the document as something of a nod to conservatives after he authored a more explosive document approving blessings for same-sex couples that sparked criticism from conservative bishops around the world, especially in Africa.

And yet, in an apparent attempt at balance, the document takes pointed aim at countries — including many in Africa — that criminalize homosexuality. It echoed Francis’ assertion in a 2023 interview with The Associated Press that “being homosexual is not a crime .”

The new document denounces “as contrary to human dignity the fact that, in some places, not a few people are imprisoned, tortured, and even deprived of the good of life solely because of their sexual orientation.”

The White House said President Joe Biden, a devout Catholic, was “pleased” to see that the declaration “furthers the Vatican’s call to ensure that LGBTQ+ (individuals) are protected from violence and imprisonment around the world,” press secretary Karine Jean-Pierre said.

On the specifics involving gender theory, Jean-Pierre stressed that it was not Biden’s role to “litigate internal church policy.”

Asked how its negative take on trans people squared with Francis’ message of welcome, Fernández said the welcome remained but that the pope fervently believed that the idea that gender was fluid “rather than helping to recognize dignity, impoverishes the vision” of a man and woman coming together to create new life.

The document is something of a repackaging of previously articulated Vatican positions, read now through the prism of human dignity. It restates well-known Catholic doctrine opposing abortion and euthanasia, and adds to the list some of Francis’ main concerns as pope: the threats to human dignity posed by poverty, war, human trafficking, the death penalty and forced migration.

In a newly articulated position, it says surrogacy violates both the dignity of the surrogate mother and the child .

While much attention about surrogacy has focused on possible exploitation of poor women as surrogates, the Vatican asserts that the child “has the right to have a fully human (and not artificially induced) origin and to receive the gift of a life that manifests both the dignity of the giver and that of the receiver.”

“Considering this, the legitimate desire to have a child cannot be transformed into a ‘right to a child’ that fails to respect the dignity of that child as the recipient of the gift of life,” it said.

The Vatican had previously published its most articulated position on gender in 2019, when the Congregation for Catholic Education rejected the idea that people can choose or change their genders and insisted on the complementarity of biologically male and female sex organs to create new life.

The new document from the more authoritative Dicastery for the Doctrine of the Faith quotes from that 2019 education document, but tempers the tone. Significantly, it doesn’t repeat Vatican doctrine that homosexual people deserve to be treated with dignity and respect but that homosexual actions are “intrinsically disordered.”

In a news conference to introduce the document, Fernández acknowledged that the “intrinsically disordered” language was very strong. He suggested there might be a better way, “with other words,” to express the church’s vision of sex between husband and wife to create new life.

Francis has ministered to trans Catholics, including trans sex workers, and insisted that the Catholic Church must welcome all children of God.

But he has also denounced “gender theory” as the “worst danger” facing humanity today, an “ugly ideology” that threatens to cancel out God-given differences between man and woman. He has blasted in particular what he calls the “ideological colonization” of the West in the developing world, where development aid is sometimes conditioned on adopting Western ideas about gender.

Transgender activists immediately called the document “hurtful” and devoid of the voices and experiences of real trans people, especially in the distinction it makes between gender-affirming surgeries and surgeries on intersex people.

“The suggestion that gender-affirming health care — which has saved the lives of so many wonderful trans people and enabled them to live in harmony with their bodies, their communities and (God) — might risk or diminish trans people’s dignity is not only hurtful but dangerously ignorant,” said Mara Klein, a nonbinary, transgender activist who has participated in Germany’s church reform project.

Klein said the Vatican “hypocrisy” was furthered by the document’s approval of surgery on intersex people, “which if performed without consent especially on minors often cause immense physical and psychological harm.”

The document comes at a time of some backlash against transgender people, including in the United States where Republican-led state legislatures are considering a new round of bills restricting medical care for transgender youths — and in some cases, adults.

“On top of the rising hostility towards our communities, we are faced with a church that does not listen and refuses to see the beauty of creation that can be found in our biographies,” Klein said in an email.

AP writer Darlene Superville contributed from Air Force One.

Biden's latest student-loan forgiveness plan brings questions for borrowers: What to know

Some student loan borrowers may not take advantage of President Joe Biden's final plan to eliminate debt for millions because they don't know if they're eligible, don't understand the process or think it is a scam.

On Monday, Biden promised student loan relief by the fall with his final proposal. This plan comes less than a year after the Supreme Court blocked his initial attempt.

Under the proposed plan, more than 4 million borrowers who have been paying down their student loans for 20 years or more could have their debt completely canceled, according to the White House. The plan would also help more than 10 million borrowers by giving them $5,000 or more in relief, Biden's administration said.

Biden also aims to help 23 million borrowers by eliminating interest past the original loan amounts.

How to apply for student loan forgiveness?

If eligible for debt relief, borrowers should periodically check their emails for updates from their student loan servicers and Federal Student Aid .

Learn more: Best personal loans

While Biden works on his final proposal, eligible borrowers can apply on the Federal Student Aid website for other kinds of relief, including if they have a disability , work for a nonprofit , or are a teacher , government employee or medical professional .

Borrowers repaying their loans for 20 to 25 years can apply for income-driven repayment (IDR) loan forgiveness.

Several other loan forgiveness options are available on the Federal Student Aid website, but borrowers should check if they're eligible by looking closely at each selection. Victims of forgery, borrowers who declared bankruptcy and Perkins loan borrowers are examples of individuals eligible for forgiveness.

What document explains your rights and responsibilities as a federal student loan borrower?

A Master Promissory Note (MPN) is a binding legal document borrowers must sign before they receive a federal student loan promising they'll repay the loans and any accrued interest and fees to the U.S. Department of Education, according to Federal Student Aid.

Student loan debt: Averages and other statistics in 2024

There is one MPN for direct subsidized/unsubsidized loans and a different MPN for direct PLUS loans. All MPNs can be signed electronically.

"You may receive more than one loan under an MPN over a period of up to 10 years to pay for your or your child’s educational costs, as long as the school is authorized to use the MPN in this way and chooses to do so," the Federal Student Aid website says.

Am I eligible for student loan relief?

By checking their emails, borrowers typically receive messages explaining whether they're eligible for relief and what type they can apply for.

If not signed up for emails, borrowers can visit the Federal Student Aid website and check their eligibility by hovering over the "loan forgiveness" tab and clicking "types of loan forgiveness."

Once the borrower clicks "types of loan forgiveness," they will be taken to a page showing the available relief options. Borrowers then can check their eligibility.

Be aware of student loan scams

Federal Student Aid warns borrowers to be aware of scams because they "might be contacted by a company saying they will help you get loan discharge, forgiveness, cancellation, or debt relief for a fee."

"You never have to pay for help with your federal student aid," the office's website says. "Make sure you work only with the U.S. Department of Education, the office of Federal Student Aid, and our loan servicers, and never reveal your personal information or account password to anyone."

The emails to borrowers come from [email protected], [email protected] and [email protected].

Borrowers can report scam attempts to the Federal Trade Commission by calling 1-877-382-4357 or by visiting reportfraud.ftc.gov.

Student loan scam involving 'Mission Hills Federal'

The Federal Trade Commission announced March 13 that it is sending more than $4.1 million in refunds to 27,584 borrowers who "lost money to student loan debt relief scammers who lured consumers with fake loan forgiveness claims and pocketed their money," according to a news release.

The scheme, which "tricked students into paying hundreds to thousands of dollars" since 2014, went by many names including Mission Hills Federal, Federal Direct Group, National Secure Processing and The Student Loan Group.

The group made the borrowers pay "illegal upfront fees and pretended to lower consumers’ monthly student loan payments," according to the FTC. The operators also deceived borrowers into sending their monthly student loan payments directly to them by "falsely claiming to take over the servicing of the consumers’ loans," the agency said.

"In reality, few payments were actually applied to consumers’ student loans and in many cases, none at all," the FTC said. "Instead, the defendants kept consumers’ money for themselves."