documentation/Writing-the-content.md

+> To follow this tutorial is better to have read [Use gitlab to edit websites](./Use-gitlab-to-edit-websites) or [Compiling a local version of the website](./Compiling-a-local-version-of-the-website) first.
+
+[[_TOC_]]
+
+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.
+
+### 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.
+
+### 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.
+
+## 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](./How-to-develop-on-the-website)
+
+## TABLES
+
+You can do tables with | characters. Example:
+
+```
+| Project  | Methodology | Locations | Dates | Reporting |
+| -------- | ----------- | --------- | ----- | --------- |
+|  |  |  |  | test      |
+```
+
+Will create:
+
+| Project  | Methodology | Locations | Dates | Reporting |
+| -------- | ----------- | --------- | ----- | --------- |
+|  |  |  |  | test      |
+
+
+--------------
+
+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`
\ No newline at end of file