1
0
Fork 0
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
blog/TIPS

115 lines
4.0 KiB
Plaintext

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)"
`reST spec <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#anonymous-hyperlinks>`__