140 lines
4.2 KiB
Plaintext
140 lines
4.2 KiB
Plaintext
Blog overview
|
|
=============
|
|
|
|
The blog consists of a set of static files sorted into folders by date. Each
|
|
file contains the content for a single blog post.
|
|
|
|
Post format
|
|
-----------
|
|
|
|
Blog posts are written in reStructuredText format. The post contents is passed
|
|
through Jinja2 before being handed to the docutils formatter, so standard
|
|
template tags and variables can be used. This allows site-internal URLs to be
|
|
correctly generated, and text to be tagged for translation.
|
|
|
|
At the top of each post, a metadata section should be included. This is parsed
|
|
to obtain informatiion about the post for use in summaries (such as the blog
|
|
index page). The following metadata is used:
|
|
|
|
- **date**: Optional, can be used to override the URL date. If set to the same
|
|
date as the URL date, it saves a Python split and join operation.
|
|
- **category**: Optional, enables posts to be categorized (each category has
|
|
its own RSS feed that can be followed, in addition to the overall feed).
|
|
- **author**: Optional, if left out the default is 'I2P devs'
|
|
- **excerpt**: Summary of the post (generally the same as the first line for
|
|
translation purposes). Required, it is displayed on the blog index.
|
|
|
|
Please use the following standard categories:
|
|
|
|
- android
|
|
- beta
|
|
- community
|
|
- conferences
|
|
- development
|
|
- general
|
|
- news
|
|
- release
|
|
- security
|
|
|
|
|
|
How to use the blog
|
|
-------------------
|
|
|
|
1. Create a directory path matching the date of the blog post, e.g.
|
|
'mkdir -p 2014/01/01'. Day and month directories MUST be two digits!
|
|
2. Create a file in that directory with suffix '.rst'. The name of the file and
|
|
the directory path will together be the URL that the post will be visible at
|
|
e.g. '2014/01/01/Happy-New-Year.rst' -> '/lang/blog/post/2014/01/01/Happy-New-Year'.
|
|
Use - for spaces in the file name.
|
|
3. Write the blog post in reStructuredText format, taking note of the custom
|
|
format notes above.
|
|
|
|
Translations
|
|
-------------
|
|
|
|
Write your post so it may be easily translated.
|
|
Inside {% trans -%}...{%- endtrans %} blocks, put line breaks after long sentences
|
|
or phrases. Do not put line breaks at random places.
|
|
|
|
|
|
Links
|
|
-------------
|
|
|
|
The goal is to keep as much formatting out of the tagged string as possible,
|
|
so that the translators are less likely to inadvertently break the formatting,
|
|
and we can change the link later without breaking translations.
|
|
This also allows us to use macros for converting to .i2p links.
|
|
|
|
External links:
|
|
|
|
For full untranslated link text:
|
|
|
|
`QUIC <https://www.rfc-editor.org/rfc/rfc9000.html>`_
|
|
|
|
For full translated link text:
|
|
|
|
`{% trans %}I2P Mac OS Easy Install bundles{% endtrans %}`__
|
|
|
|
__ https://geti2p.net/en/download/mac
|
|
|
|
or:
|
|
|
|
`{% trans %}I2P Mac OS Easy Install bundles{% endtrans %} <https://geti2p.net/en/download/mac>`_
|
|
|
|
|
|
For partial translated link text:
|
|
|
|
{% trans link1="https://...", link2="..." -%}
|
|
Blah blah `link text <{{ link1 }}>`_ more text.
|
|
<%- endtrans %>
|
|
|
|
Internal links:
|
|
|
|
As above but use, e.g.
|
|
`NTCP2 <{{spec_url("ntcp2")}}>`_
|
|
`SSU2 <{{proposal_url("159")}}>`_
|
|
This does not work: {% trans link1="{{spec_url('i2np')}}" -%}
|
|
|
|
|
|
Multiple links to the same thing:
|
|
|
|
{% trans -%}
|
|
Blah blah RFC-9001_
|
|
and RFC-9001_ again.
|
|
<%- endtrans %>
|
|
|
|
.. _RFC-9001: https://www.rfc-editor.org/rfc/rfc9001.html
|
|
|
|
|
|
RST guide: https://docutils.sourceforge.io/docs/user/rst/quickref.html#hyperlink-targets
|
|
|
|
|
|
|
|
Writing draft posts
|
|
-------------------
|
|
|
|
To write a draft post, create the file with the suffix '.draft.rst'. Post files
|
|
with this suffix will be visible at their post URL, but will not be shown in
|
|
the blog index. To publish the draft post, change the filename to remove the
|
|
'.draft' in the suffix (e.g. git mv foo.draft.rst foo.rst).
|
|
|
|
Review your formatting before checking in with the linux tool rst2html.
|
|
This will not process translation blocks, of course.
|
|
|
|
After checking in the draft, navigate to it in your browser and verify
|
|
the formatting is correct, including translation blocks.
|
|
|
|
|
|
Creating shortlinks
|
|
-------------------
|
|
|
|
See the comments in shortlinks.py.
|
|
|
|
How to make a release notice
|
|
----------------------------
|
|
|
|
1. Create a directory path matching the date of the release.
|
|
2. Find the blog post file for the previous release, and copy it into the new
|
|
directory (renaming as appropriate).
|
|
3. Edit as necessary.
|