Writing the content

To follow this tutorial is better to have read Use gitlab to edit websites or Compiling a local version of the website first.

• Markdown syntax
  • Short Sentences
  • Localization limitations
  • Links
  • Lists
  • How to write commands
  • HTML
  • Tables
• How to Name the folders

When writing the content on our different lektor-based websites, there are some things to take into account:

Markdown syntax

We work with a text format called MarkDown. You can learn about it from the link https://gitlab.torproject.org/help/user/markdown

Short Sentences

Please add linebreaks to the long sentences.

If you add only one linebreak, the paragraph will stay together, but the translation framework will generate two sentences. i.e.:

This will create one paragraph.
With the three sentences.
But it will create three translation strings in the i18n/contents.pot file.

Long sentences are hard to translate and unlikely to be reused.

Localization limitations

This will also
create three strings for translation, so
please don't do it!

Please don't create a new line in the middle of a sentence, as that creates bad translation strings:

This sentence is correct.

This sentence

not.

Links

• Links are better done as [linked words](https://link), as those are easier to review, and simpler to read when compared to <a href="https://link">.

• Always prefer internal links, for example if you are editing the tb-manual, is better to write the link as [linked words](../link) and not [linked words](https://tb-manual.torproject.org/link), because the users may be browsing through our onion address or a local documentation instance with another URL.

• Always prefer a relative link: instead of making an absolute link as in [linked words](/link), that should take you to website/link, do it as [linked words](../link) that will take you to a page relative to where you are on the website. This way the links work when we publish the website in a subdomain folder, in the staging server, and will probably work better in offline editions.

• External links:

  • Always prefer https links when available, to protect the privacy of our readers.
  • Make sure that the link is the shortest version possible, without suffixes like: ?ftag=COS-05-10aaa0b or other random stuff. Take everything possible out of the link and leave it to its minimal (as long as functional) expression.

Lists

Lists are either ordered (numbered), or unordered (bullet points).

You can write ordered lists like this. The order the numbers are in doesn't matter, they'll be renumbered when converted to HTML.

1. the first thing
2. the second thing
3. and a third thing

You can write unordered lists like this. You can use an asterisk (*), a dash (-), or a plus (+).

* foo
* bar
* baz

Warning: Note the space between the number/bullet and the list text. Forgetting the space is a common cause of confusion, because it can be hard to notice what you've done wrong.
Warning: Don't add blank lines between list items, or they'll render as separate lists. This is a quirk of Lektor's markdown parser (mistune).

How to write commands

• When writing linux commands, remember that:
  • If the command starts with $, you know that the command should be executed as regular user.
  • If it starts with #, it should be executed as root.
• Enclose the commands in '`' signs when using them mid sentence so they get some styling.

HTML

HTML is supported but not totally, and should be avoided. It is better to stick to MarkDown, as it is easier to read as code, and translate.

If you want to work on layout, css, or python related development, please read How to develop on the website

Tables

You can do tables with | characters. Example:

| Project  | Methodology | Locations | Dates | Reporting |
| -------- | ----------- | --------- | ----- | --------- |
|  |  |  |  | test      |

Will create:

How to Name the folders

Call the new folders in /content/* with a name that means something. Please avoid calling them tbb-1. It is preferable to call them as the slug field. This is better for SEO and also while browsing the repo. If you want to change the order of the items you can use the key field.

To update this wiki you can submit a merge request for the repository: git@gitlab.torproject.org:tpo/web/wiki.wiki.git or https://gitlab.torproject.org/tpo/web/wiki.wiki.git