NVDA-MarkdownForever

Full-featured Markdown and HTML converter for NVDA

1.1. Introduction

MarkdownForever is a small NVDA add-on that converts Markdown or HTML contents easily. Just write or display any text in Markdown or HTML format and press a simple shortcut to instantly convert or preview the result at any time, exactly as it will look like in your final webpage, or in HTML source code, ready to be pasted in any text area supporting HTML.

MarkdownForever can:

1.2. But what on Earth this Markdown thing is?

According to Wikipedia,

Markdown is a lightweight markup language with plain text formatting syntax.   Its design allows it to be converted to many output formats, but the   original tool by the same name only supports HTML. Markdown is often used to   format readme files, for writing messages in online discussion forums, and   to create rich text using a plain text editor.

You can learn more about Markdown by reading the full article on Wikipedia.

So, instead of writing your web documents using HTML with risk of making mistakes, you will use easy to memorize tags and your work will be done in no time. With Markdown, you will be able to do more or less the things HTML can do: headings, ordered (numbered) or unordered (buleted) lists, links, and even tables.

For example, if you want to make a first level heading, you will write one hash sign (#), followed by the name of your heading, with or without a space between them:

#This is an example of a first level heading

which will appear as follow in your final HTML document:

2. This is an example of a first level heading

For a second level heading, you will use Two hash signs, three for a third level one, Etc.

Now, let's make an unordered list of items. To do so, you can prefix all items of your list by an asterisk (*). Here is an example:

* Orange
* Sugar
* Milk

which will appear as:

  • Orange
  • Sugar
  • Milk

You can also make a link by enclosing the title of the link in square brackets ([]), followed by the URL enclosed in parentheses without any spaces. For example:

[Click here to visit NVAccess's website](https://www.nvaccess.org)

which will give you:

Click here to visit NVAccess's website

You can even put *some text in italic* by enclosing it in asterisks, or **write text in bold** by surrounding it with two asterisks... Possibilities are numerous. Just check this Markdown Cheat Sheet for more tags and details.

2.1. Converting Markdown to HTML

This feature allows you to convert any markdown text displayed on the screen to HTML, showing you the way your Markdown will look in the final HTML document. This can be a document you have written in Markdown format, a .md file you already have on your hard drive or a Markdown text found on a web page. By default, MarkdownForever converts all the currently displayed text, but you can also select only a specific part to be converted.

You can use the following commands:

Please note that it is recommended to favor the display in browser instead of the virtual buffer of NVDA. Some tags, particularly HTML5 tags such as <details>, are not supported by the render of virtual buffer.

2.2. Converting Markdown to HtML source code

This converts Markdown text to pure HTML language. Once done, you'll be able to copy and paste it in an HTML file, in a forum post, or any text area on the web where HTML code is supported.

The following commands are available:

2.3. Converting HTML to Markdown

This feature attempts to produce a Markdown text from an HTML source content. As usual, this works on the entire text displayed on the screen or on a specificly selected part. The following commands are available:

You can also convert an HTML web page to Markdown by simply selecting its URL. However, you must first ensure that the HTML2Text conversion engine is properly set as the default one in MarkdownForever's settings, located in the Settings sub menu of NVDA.

2.4. Converting Markdown to Formatted HtML

This function converts your Markdown content to formatted HTML and copy it to the clipboard. Formatted HTML will look like any web page displayed by your browser, with clickable links, headings etc. This can only be generated from a Markdown content. It doesn't work with HTML source code. To perform this action, press NVDA+Shift+h.

Please note that the formatted HTML can be pasted in applications like Microsoft Word, Wordpad, Thunderbird, some rich-text field in web page, etc. However it can't be pasted in text editor such as Notepad, Notepad++, etc.

2.5. Interactive Mode

The interactive mode is a function which presents all MarkdownForever's features in a convenient dialog box, which offers you even more handy extras. To open the Interactive Mode, Press NVDA+CTRL+i. Here is a description of the screen in Tab order:

2.6. Optional Metadata block

The metadata block allows you to set specific parameters for a particular document, independent of the default settings. This must be placed at the very beginning of the document and must begin with three dashes ("---") and end with three periods ("...") or three dashes ("---"). Each entry must be inputted in the following form: key: "value" (the value must be enclosed in quotes). An empty line must be present after the metadata block.

2.6.1. List of supported metadata

2.6.2. Metadata usage example

---
title: "a simple title"
date: 2019-11-08
subtitle: "this is the subtitle of your document"
lang: en
author:
- John Doe
- David Murphy
CSS:
- %userprofile%/document/main.css
- %userprofile%/document/custom.css
keywords: NVDA, Markdown, HTML
filename: test
path: "%userprofile%/desktop"
toc: 0
autonumber-headings: 1
mathjax: 0
---

Hello World! <span lang="fr">Bonjour tout le monde!</span> <span lang="es">buenos días!</span>

In the example above, the text will be voiced in three languages, assuming that the voice synthesizer you are using supports automatic language switching and the corresponding checkbox is ticked in NVDA speech settings. It will sound as follows:

Hello World! Bonjour tout le monde! buenos días!

2.7. Extra-tags

Extra-tags are special placeholders that you can put in your Markdown content to automatically add system info like current date or time, which will be rendered in clear text in your HTML document.

2.7.1. Supported extra-tags

In the Markdown content Explanation Result in the browser
%date% Current date 12/9/2019
%time% Current time 6:59:06 AM
%now% Current date / time 12/9/2019 6:59:06 AM
%day% Current day (long format) Monday
%dday% Current day (decimal format) 09
%month% Month (long format) December
%dmonth% Current month (decimal format) 12
%year% Current year (2 digits) 19
%Year% Current year (4 digits) 2019
%toc% Table of contents at cursor's position (if enabled through metadata or default settings) N/A

2.8. MarkdownForever's default settings

They can be reached from the NVDA menu -> Settings MarkdownForever -> Settings and will let you configure and set as default various settings related to the conversion process already mentionned above:

2.9. Commands summary

2.10. Add-on Information