parent
2ba1cf43d6
commit
1c841e2138
@ -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 <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>`__
|
||||
@ -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
|
||||
Loading…
Reference in New Issue