From 1c841e213851726cf5d5df10da71b9477da1a8db Mon Sep 17 00:00:00 2001 From: Pavel 'LEdoian' Turinsky Date: Tue, 28 Feb 2023 11:24:43 +0100 Subject: [PATCH] Add a few cheat sheets / templates Making my blogging easier :-) --- TIPS | 114 +++++++++++++++++++++++++++++++++++++++ frontmatter_template.rst | 13 +++++ 2 files changed, 127 insertions(+) create mode 100644 TIPS create mode 100644 frontmatter_template.rst diff --git a/TIPS b/TIPS new file mode 100644 index 0000000..1a86077 --- /dev/null +++ b/TIPS @@ -0,0 +1,114 @@ +General syntax: + (I might have the taxonomy wrong) + - Inline directives: :directive:`parameters or content` + - I think in most cases the backticks can be omited for single word. + - Block directives: + .. directive:: + :param:value + :another:param + + content + - Various weird syntax inline + - I am not sure if everything can be written using directives. + - Basic formatting: + *emph*, **bold**, ``monospace`` + - I have no idea what kind of indentation should work and what should not, + esp. regarding indented code blocks in lists, continuing list items after + the block, starting the code block with a space, etc. + +Links: + `text `__ + - Two underscores to not create labelled link, so that we can have more links with `text` + - The rationale seems to be to have readable postponed links gemtext style: + This is some text with a `link`_ that does not break flow of reading + + .. _link: https://target.example + ``__ works too + - Much better feeling than the implicit "put an IANA scheme at the + start or '@' in the middle and it will automagically work." + Unfortunately, I don't know how to disable the implicit behaviour. + ` ``…`` … <…>`_ will *not* work. + - Workaround: this is a |link|. + .. |link| replace:: link text + .. _link: URL + + - Link targets can be also headings and other stuff. In case we want a label, we can create either _`an inline label`, or + .. _`block label`: + The block label binds to the next paragraph, i.e. this. If I rant in + comments in between, it binds to the rant and creates the ``
``s wrong. + +Headings: + - Need to underline the whole string (cannot be shorter) + - Does not matter which character is used. Character of first heading is + for h1's, the next not-yet-used character is for h2, etc. + - Do *not* use ``:title: My best article`` in frontmatter. While that + works, reST throws a warning that it does not have unique title if + multiple second-order headings are present. + - Frontmatter can follow the heading after a blank line. + - Convention: + - @@@@ for article titles + - ==== for main headings + - ---- for the next ones + - ```` for h3 + + - This aims to copy Markdown for most parts. + +Comments: + - A hack: '.. ' after which there is no recognised directive. It seems that + directives either contain "::" or start with weird characters like + underscores and pipes. It seems unlikely to accidentally match, but still feels wrong. + - Preserved in HTML + +Code and verbatim: + - The basic case has just two colons at the end and a level of indentation:: + I am verbatim + - No customisation though + - Magic rules about the T_PAAMAYIM_NEKUDOTAYIM to do the right thing: + - next to a word ([a-z]+) it reduces to single colon + - after space vanishes completely I think + - Code block can be written with ``.. code-block::`` and customized. + +Pelican frontmatter: + Title + @@@@@ + + :date: 1970-01-01 14:24 + :slug: my-best-article + :tags: super, best, exciting + :category: whatever + :lang: en + :translation: false + :status: hidden (or draft or published) + + The docs have a table of what keys are allowed. Most of the keys are not + required and Pelican will try to guess (like create slug from title or put + everything in ``misc`` category), but the guesses are not that great. + + As written above, ``:title:`` works too but creates unnecessary warnings. + + For Markdown, use (yanked from ofic. docs): + Title: My First Review + Date: 2010-12-03 10:20 + Category: Review + +Tables: + - The only usable ones are list-tables and csv-tables. Other need some + ASCII art, which is pain to generate and track in git. + + .. list-table:: Table title + :header-rows: 1 + + * - Left header + - Right header + * - Top left cell + - Top right cell + * - Bottom left cell + - Bottom right cell + + .. csv-table:: Optional title + :header: "Name", "Age", "Language" + + "LEdoian", "young", "Python" + "Knuth", "older", "CWEB (IIRC)" + +`reST spec `__ diff --git a/frontmatter_template.rst b/frontmatter_template.rst new file mode 100644 index 0000000..a90fe4d --- /dev/null +++ b/frontmatter_template.rst @@ -0,0 +1,13 @@ +Title +@@@@@ + +:slug: an-article-to-read +:date: 1970-01-01 00:00 +:tags: wip +:category: random +:keywords: unwritten, template, accidentally published +:lang: en +:translation: false +:status: draft + +.. Please write some content ffs