blog/TIPS

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 <URL>`__
		- 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
	`<URL>`__ 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 ``<div>``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)"

Images and Figures:
	- Do not use .. image::, because that makes no wrapping element, using which we could center the image
	- Usage::

	  .. figure:: {static}/images/some/path.ext
	     :width: 100%
	     :alt: Hello world

	     This is a caption.
	- Of course, using just the path is sufficient.

Footnotes:
	This is a text with an autonumberred[#fnlabel]_ footnote.

	.. [#fnlabel] And this is the text of the footnote, whereever I place it.

`reST spec <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#anonymous-hyperlinks>`__