Archive for the ‘Lightweight markup language’ Category
Posted by jpluimers on 2020/04/22
When fixing some of the Pandoc conversion messages from … to html, I got this warning:
Network-Protocol-Security.rst:917: (WARNING/2) Inline substitution_reference start-string without end-string.
In my experience, the line numbers do not usually match, but in this case it was accurate (not the same as Network-Protocol-Security.rst#L874 because I was still editing it).
A search for “Inline substitution_reference start-string without end-string.” did only reveal occurrences, not causes, but “Inline substitution_reference start-string without end-string”
showed post with a cause: [WayBack] python sphinx – How to include an internal reference in a code block? – Stack Overflow pointing to [WayBack] reStructuredText Markup Specification: Substitution References.
Solution is either to
- Escape
|_ using a backslash like \|-.
- Properly format code blocks using
:: at the front and indents of the block
Lessons learned:
- When you get a pandoc message like
substitution_reference, then search for it while substituting the underscore with a space inside the [WayBack] reStructuredText Markup Specification.
- Quoted strings to trim down Google search results, but you might want to leave out trailing punctuation.
Applying the lessons
Read the rest of this entry »
Posted in Development, Lightweight markup language, reStructuredText, Software Development | Leave a Comment »
Posted by jpluimers on 2020/04/21
Always watch how you format your reStructuredText sections: [WayBack] Docutils FAQ: 2.6 How can I indicate the document title? Subtitle?
That is why I have these comments at the top of most of my documents:
.. $ %
.. # * = + ^ ~ - : . _ ` ' "
The first two are the document title and subtitle marks, the others the level 1 through 13.
–jeroen
Posted in Development, Lightweight markup language, Power User, reStructuredText | Leave a Comment »
Posted by jpluimers on 2019/11/19
A few days after filing <path> disappears from "Preview" rendering and also from actual rendering (at least in issues), I realised that this is by intent: Markdown allows to [WayBack] inline html which means that code like below will be all treated as such:
<path>
> <path>
*<path>*
**<path>**
> *<path>*
> **<path>**
The solution is to either escape or quote with back-ticks:
`<path>`
> `<path>`
*`<path>`*
**`<path>`**
> *`<path>`*
> **`<path>`**
Since WordPress also is based on pseudo-HTML codes, it too needs escaping.
–jeroen
Posted in Development, Lightweight markup language, MarkDown, Power User, Software Development | Leave a Comment »
Posted by jpluimers on 2019/08/23
Since I needed to know how to formulate external hyperlinks on a Wiki page: [WayBack] Help:Links – MediaWiki.
Too many options, not even counting other sections on that page I did not quote, so I went for the first.
To create an external link, usually to a page at a different website, enclose the URL followed by space and the link text in single square brackets (see examples below). When you save or preview the page, you will see a link rendered slightly differently than an internal wikilink. It may be a different color and/or be followed by an arrow icon to show that it may lead to another site.
| Description |
You type |
You get |
| External link with specified link text |
[https://mediawiki.org MediaWiki]
|
MediaWiki |
| Numbered external link |
[https://mediawiki.org]
This is what happens if you omit the link text. Multiple links of this type on the same page are numbered sequentially. |
[1] |
| Bare external link |
https://mediawiki.org
URLs beginning with “http://” and “https://” are automatically linked, even when no brackets are used. |
https://mediawiki.org |
| Avoiding auto-linked URLs |
<nowiki>https://mediawiki.org</nowiki>
|
https://mediawiki.org |
| Protocol-relativeexternal link |
[//en.wikipedia.org Wikipedia]
[//en.wikipedia.org //en.wikipedia.org]
The link will be HTTP or HTTPS depending on the protocol of the page currently being viewed (which could be different for different users). This is only supported inside of square brackets [ ]. Using “//en.wikipedia.org” by itself does not result in a link. |
Wikipedia
//en.wikipedia.org |
| External link to the current server |
https://{{SERVERNAME}}/pagename
|
https://www.mediawiki.org/pagename |
| External link to other host passing the pagename |
https://google.com/search?q={{PAGENAMEE}}
See also: URL encoded page names, PAGENAMEE encoding |
https://google.com/search?q=Links |
| Mailto link |
[mailto:info@example.org email me]
|
email me |
| Mailto named with subject line and body |
[mailto:info@example.org?Subject=URL%20Encoded%20Subject&body=Body%20Text info]
|
info |
| Custom URI |
[skype:echo123 call me]
Any URI you wish to add needs to be first declared through $wgUrlProtocols. (This example is not enabled on Mediawiki.org) |
[skype:echo123 call me] |
| External links with file-type icons |
[https://en.wikipedia.org/wiki/.avi video]
[https://en.wikipedia.org/wiki/.ogg sound]
[https://en.wikipedia.org/wiki/.pdf document]
See External link icons for currently supported icons and extensions. Note that this wiki is not set up to use such icons. |
video
sound
document |
–jeroen.
Posted in Development, Lightweight markup language, MediaWiki, Power User | Leave a Comment »
Posted by jpluimers on 2019/08/20
After blogging on Markdown notes in 2014, Markdown support has come a long way. It also means that the documents written in Markdown has become more complex, and that more tools can render it.
Given the vague aspects of many Markdown dialects, rendering can be troublesome (see my post Babelmark 2 online Markdown checker), so below are some links on some aspects I had trouble with getting right.
Note that there are two markdown linters:
Sometimes, issues are present in one, but not in the other; see:
The command line interface to the Ruby version is easier to install than the JavaScript version as everything is in one gem: mdl, unlike the npm, where the cli is in markdown-cli and the library in markdownlint.
–jeroen
Related:
Read the rest of this entry »
Posted in *nix, *nix-tools, Development, Lightweight markup language, MarkDown, pandoc document converter, Power User, Ruby, Software Development | Leave a Comment »
Posted by jpluimers on 2019/06/17
Comments that are not emitted to the output:
The most platform-independent syntax is
(empty line)
[comment]: # (This actually is the most platform independent comment)
Thanks nick-volynkin for answering this at [WayBack] syntax – Comments in Markdown – Stack Overflow.
–jeroen
Posted in Development, Lightweight markup language, MarkDown | Leave a Comment »
Posted by jpluimers on 2019/01/09
Though normally you would write documentation in reStructuredText, then generate HTML or PDF, often you find a part of the documentation source in HTML.
Here are some sites and tools I’ve used to convert HTML fragments to reStructuredText. I favour on-line over local command-line tools as usually these kinds of conversions are “one-time only”.
–jeroen
Posted in Development, Lightweight markup language, reStructuredText, Software Development | Leave a Comment »
Posted by jpluimers on 2019/01/03
TL;DR: use Markdown Tables generator – TablesGenerator.com as it has the most features.
A few tools that help converting CSV (with separators like comma, semicolon and tab) to Markdown online:
- [Archive.cs] Markdown Table Maker
- Supports:
- Use first line as headers
- Auto detection of separator
- Tab separated
- Comma separated
- Semicolon separated
- Does not support:
- [WayBack] CSV to Markdown Table Generator — Donat Studios
- Supports:
- Use first line as headers
- Tab separated
- Comma separated
- Semicolon separated
- Does not support:
- [WayBack] Markdown Tables generator – TablesGenerator.com
- Supports auto detection of:
- Use first line as headers
- Tab separated
- Comma separated
- Semicolon separated
- Quote characters
–jeroen
Posted in CSV, Development, Lightweight markup language, MarkDown, Power User, Software Development | Leave a Comment »
Posted by jpluimers on 2018/11/14
Source: reStructuredText Directives – Images:
Inline images can be defined with an “image” directive in a substitution definition.
The |biohazard| symbol must be used on containers used to
dispose of medical waste.
.. |biohazard| image:: biohazard.png
–jeroen
Posted in Development, Lightweight markup language, reStructuredText, Software Development | Leave a Comment »
Posted by jpluimers on 2018/11/07
Some markdown tools have their own page online allowing you to experiment with their rendering; [WayBack] markdown-it demo is one of them.
I was looking for a page showing the renderings of many engines in order to improve my markdown writing skills.
I found the [WayBack] babelmark2 online markdown checker, which works great.
- It runs the markdown through various processors showing either the log with HTML produced, or a view of the rendered output.
- It has one limitation: 1000 characters of markdown text so the markdown rendering servers will not get overloaded.
Documentation is at [WayBack] Babelmark 2 – FAQ.
In addition, this is also very useful: [WayBack] markdownlint demo Demo for [WayBack] GitHub – DavidAnson/markdownlint: A Node.js style checker and lint tool for Markdown/CommonMark files.
Note that the Visual Studio Code markdownlint support, uses the above markdownlint, which is a different one than the Ruby based [WayBack] GitHub – markdownlint/markdownlint: Markdown lint tool.
Both are far easier to use than [WayBack] GitHub – michelf/mdtest: Test suite for Markdown implementations.
Via
–jeroen
Read the rest of this entry »
Posted in Development, Lightweight markup language, MarkDown, Software Development | Leave a Comment »
The Wiert Corner - irregular stream of stuff 