Archive for the ‘reStructuredText’ Category
Posted by jpluimers on 2025/02/17
Every now and then you bump into an interesting post on a workflow you already have but did not know the name for.
This time it is [Wayback/Archive] Introduction to the Zettelkasten Method which has this nice definition:
A Zettelkasten is a personal tool for thinking and writing. It has hypertextual features to make a web of thought possible. The difference to other systems is that you create a web of thoughts instead of notes of arbitrary size and form, and emphasize connection, not a collection.
I thought a bit about it and it feels quite a bit like this blog: the ~5k draft posts at the time of writing are similar to a Zettelkasten: short notes with title and links either internally or externally.
These drafts are private, but the actual blog posts are either public (already published: some 8k at the time of writing) or queued for publication (some 2 years at the time of writing).
Read the rest of this entry »
Posted in Blogging, Development, documentation, Knowledge Worker, LifeHacker, Lightweight markup language, MarkDown, Power User, reStructuredText, SocialMedia, Software Development | Tagged: developer, Productivity, Python, shorts, tips | Leave a Comment »
Posted by jpluimers on 2025/01/22
For my list archive; need to check this out because reStructuredText by LeXtudio Inc. got redesigned, deferring much of its behaviour to Esbonio.
Anyway:
For me, figuring that out under pressure how to get this to working was too much, so I deferred that to a later point in time and perform a reStructuredText to Markdown conversion in stead (I wasn’t using very esoteric .RST features, and since most people use Markdown anyway it made the documents even more accessible for others to extend). Links on that conversion:
Both Markdown and reStructuredText are problematic for background images, so I opted to cut the conference background slide in half, put the top part above the title, and the bottom half below the final part of the presentation, as this didn’t really work well either:
Oh, and for Visual Studio Code:
Queries:
--jeroen
Posted in Development, Lightweight markup language, reStructuredText, Software Development | Tagged: 22728, 3277 | Leave a Comment »
Posted by jpluimers on 2023/03/29
I’ve switched to either Markdown or reStructuredText for documentation purposes a while ago.
Often Twitter threads or Tweets are a useful addition to that, so it makes sense being able to convert them to a more portable format, especially since both Markdown and reStructuredText render well on GitHub (including Gists) and GitLab (including Snippets).
So here are some links that hopefully will get me going in the future:
–jeroen
Posted in Development, Lightweight markup language, MarkDown, reStructuredText, Software Development | 1 Comment »
Posted by jpluimers on 2020/06/12
It looks like few of the markdown parsers can generate a table without a header: [WayBack] Create table without header in markdown – Stack Overflow.
This comes close in some generators as they generate a half-height empty header for it:
| | | |
|-|-|-|
| Normal Key| Value1 |
|__BoldKey__| Value2 |
But [WayBack] reStructuredText Markup Specification: Grid Tables do support it even if a pipe cell delimiter is inside a cell content:
+--------------+----------+-----------+-----------+
| row 1, col 1 | column 2 | column 3 | column 4 |
+--------------+----------+-----------+-----------+
| row 2 | Use the command ``ls | more``. |
| | |
+--------------+----------+-----------+-----------+
| row 3 | | | |
+--------------+----------+-----------+-----------+
–jeroen
Posted in Development, Lightweight markup language, MarkDown, reStructuredText, Software Development | Leave a Comment »
Posted by jpluimers on 2020/04/23
I love Visual Studio Code, but my initial tries to get [WayBack] GitHub – vscode-restructuredtext/vscode-restructuredtext: reStructuredText Language Support in Visual Studio Code to work partially failed: editing works, but I got a non-descriptive error during preview.
All prerequisites are installed, so I needed to pause that for a while.
I still want it, as out of the box, [WayBack] Markdown editing with Visual Studio Code: Markdown Preview works fine, but for complicated documents I tend to use reStructuredText.
Initial steps were simple, as per [WayBack] reStructuredText – Visual Studio Marketplace and editing is awesome (thanks to [WayBack] GitHub – lextm/restructuredtext-antlr: ANTLR Grammar for reStructuredText).
–jeroen
Read the rest of this entry »
Posted in .NET, Development, Lightweight markup language, reStructuredText, Software Development, Visual Studio and tools, vscode Visual Studio Code | Leave a Comment »
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/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 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/04/13
One of the cool Github features is that it renders reStructuredText (and other markup documents like markdown).
Often however, your .rst file on GitHub looks very differently on GitHub as your local render. Heck: sometimes Github will not even render it at all.
–jeroen
Posted in Development, Lightweight markup language, MarkDown, Power User, reStructuredText, Software Development | Leave a Comment »
The Wiert Corner - irregular stream of stuff 