www/blog

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.