README.md 35.5 KB
Newer Older
D Sal's avatar
D Sal committed
1
## Table of Contents
D Sal's avatar
D Sal committed
2

3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
- [Introduction](#introduction)
- [What you'll need](#what-youll-need)
- [General change recommendations](#general-change-recommendations)
- [housekeeping](#housekeeping)
- [Updates on User Guides](#updates-on-user-guides)
- [How to make a blog post](#how-to-make-a-blog-post)
- [How to make a User Guide](#how-to-make-a-user-Guide)
- [How to make a Moneropedia entry](#how-to-make-a-moneropedia-entry)
- [How to update the Team page](#how-to-update-the-team-page)
- [How to make an Event](#how-to-make-an-event)
- [How to update the Roadmap](#how-to-update-the-roadmap)
- [How to add a new Merchant](#how-to-add-a-new-merchant)
- [How to add a question to the FAQ](#how-to-add-a-question-to-the-faq)
- [How to add a publication to the Library](#how-to-add-a-publication-to-the-library)
- [Localization](#localization)
  - [How to translate a page](#how-to-translate-a-page)
  - [How to add a new language](#how-to-add-a-new-language)

## Introduction
22
This README here to walk you through everything you need to know to make changes, edits, or even completely new pages for the new [getmonero.org website](https://getmonero.org/). It'll definitely be a bit of a ride, so strap yourself in.
23
Feel free to skip down to a relevant section if you already know what you need.
D Sal's avatar
D Sal committed
24

25
If you need support about something related to the website, plese join `#monero-site` on Freenode (also relayed on Matrix and mattermost). For general info about Monero join `#monero`. We'll do whatever we can to help you.
D Sal's avatar
D Sal committed
26

27
## What you'll need
D Sal's avatar
D Sal committed
28

29
* Jekyll: [getmonero.org](https://getmonero.org/) is made using a simple, static website generator called [Jekyll](https://jekyllrb.com/). You will need it installed on your system to test any changes that you made. If you're using Windows, you will want to check out [this site](http://jekyll-windows.juthilo.com/) for instructions on how to get Jekyll working on your system. If you're using a Linux-based system you can just follow the instructions on the website to get up and going:
30 31 32
  * Install Ruby
  * Install Bundler: `gem install bundler`
  * Install Jekyll with all dependencies (run from the project directory): `bundle`
D Sal's avatar
D Sal committed
33

34
* GitHub/GitLab: Pretty much everything in Monero is hosted on [GitHub](https://github.com) or [getmonero GitLab](https://repo.getmonero.org/users/monero-project/projects)and uses Git as the primary version control system. If you're not familiar with how to use Git, you can check out [this tutorial](https://guides.github.com/activities/hello-world/) for a good overview. It will take you through pretty much everything you'll need to know to edit the website. If you haven't already, register on GitLab and fork the [Monero Website repository](https://repo.getmonero.org/monero-project/monero-site).
D Sal's avatar
D Sal committed
35

36
* Markdown experience: To write pages, you're going to need to know how to use Markdown. It's basically an in-between language that enables people who don't know HTML to just write, and it will be compiled into HTML for you. You can find a great Markdown cheat sheet with examples [here](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). IF you need more help, Google and YouTube are great resources.
D Sal's avatar
D Sal committed
37 38 39 40 41

*Note: If you're confused, feel free to click other files in the same directory (folder) that you are in for the step that you are on to see some working examples. Compare them to the instructions and you should understand better.*

Once you have the above list of things, it's typically a good idea to build the website from your local computer to make sure it works before you make any changes. To do this, complete the following steps:

42
1. Navigate to your local `monero-site` repository.
43
2. Serve the website: `bundle exec jekyll serve --baseurl ''`
D Sal's avatar
D Sal committed
44 45 46 47
3. Open a browser and go to [http://127.0.0.1:4000](http://127.0.0.1:4000).
4. If all went well, you should see the Monero website and you're ready to make changes.


48 49
## General change recommendations
The average Monero user that will want to contribute to the website should probably start looking for issues labelled [⛑️ help needed](https://repo.getmonero.org/monero-project/monero-site/issues?label_name%5B%5D=%E2%9B%91%EF%B8%8F++help+needed) or making blog posts, user guides or Moneropedia entries; all of which are covered in this document. If this is all you want to do, don't worry, it's actually not a daunting task at all. If you are not well versed in web development however, it is not recommended you try to do anything beyond that.
D Sal's avatar
D Sal committed
50

51
If you are a web developer and would like to make large macro-level changes, it would be best to get in contact with rehrar and the developers on `#monero-site` or `#monero-dev` (IRC/Freenode, MatterMost, Matrix). The HTML/CSS framework is custom, though quite easy to use for a seasoned developer. Still, there are some pages that are more complicated than others and would require fair amounts of styling changes should the structure change significantly.
D Sal's avatar
D Sal committed
52

53
This website is completely open-source however and anything and everything is available for changing should the community deem it necessary.
D Sal's avatar
D Sal committed
54 55 56

Every section from here on out will talk about how to make a specific type of web page. It will start with a bullet point list of what to do for the advanced among you that just want a quick overview. For those who are still learning this list is followed by a detailed explanation, starting with example front matter. Any variable in the front matter written in all caps you are expected to change (make sure your changes are not all caps though). It will then lead you through the rest of the process until it's time to type your content.

57 58 59
A few random points of note:

- All external links must have http:// or https:// in front of them or they will not redirect properly.
60
- If you want to add a new page to the navigation, you should go to ALL LANGUAGES in the `_data/lang` folder including `template` and add the page.
61
- It is strongly strongly STRONGLY encouraged that if you make a change, you - at the minimum - test it on your local machine before submitting a PR. Sometimes unexpected things may happen due to a change. If you change a page, check the whole page on multiple screen sizes and browsers to make sure there wasn't any collateral damage.
D Sal's avatar
D Sal committed
62

63
## Housekeeping
64

65
### Editing the Site
66 67
When you make an edit to ANY page on the English language of this website, PLEASE copy your changes into the corresponding `/_i18n/template/` file as well.

68
The Monero Localization workgroup will do their best to keep tabs on all changes of the site, but it'd be nice to notify them that you've changed a page so they can make sure the equivalent pages are changed accordingly in the other languages.
69

70 71
### GitLab Issues
We ask that if you open an issue on the site that you remain available for clarifying questions or corrections. We do our best to close issues that are resolved when we make changes to the site, but If your issue is resolved by a contributor and the issue is not closed we ask that you close it in a timely manner. A contributor may ask you to close an issue after it's confirmed fixed. Please review the changes to the site and close your issue if you can verify that it's fixed.
72

73
### Pull Requests
74
Contributors should use [issue keywords](https://docs.gitlab.com/ee/user/project/issues/automatic_issue_closing.html) to make it easier for maintainers to close issues when they merge. Include close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved, etc in the commit message or pull request description, so that the correct issue can be closed if your PR is merged. (Example: 'fixes #1234' could close Issue 1234 when merged.)
75

76
Pull requests allow others to make comments or review your changes to the site. We ask that you remain available to comment or make changes to your PR. Pull requests with pending changes for more than 30 days will be closed and need to be resubmitted in the future. Sometimes someone else's changes might make your changes conflict with the current site. If that happens you may need to rebase your PR.
el00ruobuob's avatar
el00ruobuob committed
77

78
## Updates on User Guides
el00ruobuob's avatar
el00ruobuob committed
79 80
User guides and developer guides may need regular updates, either to fix typos, to add explanations regarding new features, to update screenshots, and so on.
As those guides are translated in several languages, it could be hard to keep all languages version up to date with the English version.
Dimitris Apostolou's avatar
Dimitris Apostolou committed
81
To keep track of those changes, guides are versioned using a snippet at the top of each localized (\_i18n/en/resources/\*-guides) file:
el00ruobuob's avatar
el00ruobuob committed
82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100
```
{% assign version = '1.1.0' | split: '.' %}
```
This snippet is responsible for keeping track of the language version.

The based version (English version) is however also tracked in the `Front Matter` from the /resources/user-guides/ or /resources/developer-guides/ directory file:
```
mainVersion:
  - "1"
  - "1"
  - "0"
```

- First number is the Major version number
- Second number is the Minor version number
- Third number is the build number.

When you update a guide, you are responsible for updating this version tracking in every file involved in your update:

Dimitris Apostolou's avatar
Dimitris Apostolou committed
101 102
- For an update on English files, you will update the version tracking number in the `Front Matter` of /resources/\*-guides/ and in \_i18n/en/resources/\*-guides
- For an update on localized files, you will update the version tracking number in the \_i18n/<local>/resources/\*-guides only, and
el00ruobuob's avatar
el00ruobuob committed
103 104 105 106 107 108 109 110 111
  - You will not update to a higher Major or Minor version number than the reference English guide
  - If you want to update to a higher Major or Minor version number, you should update the English version accordingly so that English is always the highest Major.Minor version.

And you will increment the version number in the following way:

- Cosmetic change only (typo, rephrasing, screenshot update with exact same field names and positions): Increment the third number (build number). We do not want to even warn the user about this update in another language.
- Changes that add instructions or explanations (or screenshot updates with different field names and positions), without making the old version misleading for users: Increment the second number (Minor version number) and reset the third to 0. We want to let the user know the English version could be more accurate and helpful to read.
- Changes that makes the old version false, or misleading to users: Increment the first number (Major version number) and reset the second and third to 1.0. We want to discourage users from reading this too outdated version that could lead them to do wrong things (for instance, buy the wrong algo of mining power on nicehash, after a pow change).

112
## How to make a blog post
D Sal's avatar
D Sal committed
113

114
### 1. Quick Start
el00ruobuob's avatar
el00ruobuob committed
115
* Make new .md file in \_posts (named whatever, no spaces)
D Sal's avatar
D Sal committed
116 117 118 119 120
* Front Matter (below)
* Write Blog Post
* Test/Build
* Submit PR

121
### 2. Make a file
el00ruobuob's avatar
el00ruobuob committed
122
Navigate to the \_posts folder of the website and make a new file. Be sure the file name has no spaces and the ending is .md
D Sal's avatar
D Sal committed
123

124
### 3. Front Matter
D Sal's avatar
D Sal committed
125 126 127 128 129 130 131 132 133 134
```
---
layout: post
title: CHANGE TO YOUR TITLE
summary: A BRIEF ONE OR TWO SENTENCE SUMMARY
tags:  [CHOOSE, RELEVANT, TAGS, AND, SEPARATE, THEM, BY, COMMAS, KEEP, THE, BRACKETS]
author: YOUR NAME OR HANDLE HERE
---
```

135
### 4. Write
el00ruobuob's avatar
el00ruobuob committed
136
After the front matter is finished you are free to write the remainder of your blog post in markdown.
D Sal's avatar
D Sal committed
137

138
### 5. Build/Test
D Sal's avatar
D Sal committed
139 140
Build your website using `jekyll serve` if it's not rebuilding automatically and test that your page appears in the 'News' section of the website, as well as the sidebars.

141
### 6. Submit Pull Request
D Sal's avatar
D Sal committed
142 143
You're all done. Submit a PR and wait for it to be reviewed and merged. Be sure to make any changes if requested.

144
## How to make a User Guide
D Sal's avatar
D Sal committed
145

146
### 1. Quick Start
D Sal's avatar
D Sal committed
147

148 149
* Create file in /resources/user-guides with an .md ending and no spaces in filename.
* File content as in 5.3
el00ruobuob's avatar
el00ruobuob committed
150
* Create file in /\_i18n/en/resources/user-guides with the exact same filename as above ending in .md
D Sal's avatar
D Sal committed
151
* Write User Guide
el00ruobuob's avatar
el00ruobuob committed
152
* Add versioning snippet
el00ruobuob's avatar
el00ruobuob committed
153
* Copy User Guide file to ALL LANGUAGES in /\_i18n/[ALL LANGUAGES]/resources/user-guides
el00ruobuob's avatar
el00ruobuob committed
154
* set translation to false in the snippet the top of each language version of your User Guide, except the original language
el00ruobuob's avatar
el00ruobuob committed
155
* Add guide using markdown in the correct category, and in alphabetic order, in ALL LANGUAGES to /\_i18n/[ALL LANGUAGES]/resources/user-guides/index.md being careful not to mess with any indentation
D Sal's avatar
D Sal committed
156 157 158
* Test/Build
* Submit PR

159
### 2. Make a file
D Sal's avatar
D Sal committed
160 161
Navigate to the /resources/user-guides folder and make a new file. Be sure the file name has no spaces and the ending is .md

162
### 3. Content of file
D Sal's avatar
D Sal committed
163 164
```
---
165
layout: user-guide
D Sal's avatar
D Sal committed
166
title: TITLE OF YOUR USER GUIDE
167
permalink: /resources/user-guides/NAME-OF-FILE-GOES-HERE.html
el00ruobuob's avatar
el00ruobuob committed
168 169 170 171
mainVersion:
  - "1"
  - "1"
  - "0"
D Sal's avatar
D Sal committed
172
---
173 174

{% tf resources/user-guides/NAME-OF-FILE-GOES-HERE.md %}
D Sal's avatar
D Sal committed
175 176
```

177 178
Copy this exactly and merely change the files names where indicated.

179
### 4. Create file in localization folders
180 181
Navigate to the /i18n/ folder and choose the correct folder for your language. Navigate further into the `resources/user-guides` folders and make a .md file with the EXACT SAME filename as the you made before.

182
### 5. Write
D Sal's avatar
D Sal committed
183 184
Write your user guide. Be succinct but thorough. Remember, people will be using your guides when they need help. Make sure all the information is there. Feel free to use images or screenshots if necessary to help get your point across.

185 186
The title should be at the top of the User Guide using a single `#` for an H1 tag. Titles will not be automatically put on these pages as with other pages. There should be NO front matter on this file.

el00ruobuob's avatar
el00ruobuob committed
187 188 189 190 191
Add the version snippet at the top of your guide (before your title):
```
{% assign version = '1.1.0' | split: '.' %}
{% include disclaimer.html translated="true" version=page.version %}
```
Dimitris Apostolou's avatar
Dimitris Apostolou committed
192
Your version should start at `1.1.0` as it is the first Major, first Minor, and no cosmetic changes have occurred.
el00ruobuob's avatar
el00ruobuob committed
193

194
### 6. Copy User Guide file into all languages
195 196
Copy your file and navigate to each language file in the /i18n folder. In each language folder (INCLUDING template) go to the resources/user-guides folder and paste your user guide (don't worry, you don't have to translate it) there. This is very important, and the site will not build if the file with the same name is not in each language folder.

el00ruobuob's avatar
el00ruobuob committed
197 198
As you paste into each folder, open up the file and edit the snippet at the top of the file (before your title) to mark it untranslated:
`{% include disclaimer.html translated="false" version=page.version %}`. This does not need to be done in the original language that the User Guide was written in.
199

200
### 7. Add Guide to the 'User Guide' landing page of EACH LANGUAGE
el00ruobuob's avatar
el00ruobuob committed
201
In the /\_i18n/[ORIGINAL LANGUAGE OF USER GUIDE]/resources/user-guides folder, find the file labeled index.md and open it.
D Sal's avatar
D Sal committed
202 203 204 205 206

DO NOT CHANGE ANYTHING IN THIS DOCUMENT BESIDES WHAT YOU ARE INSTRUCTED TO.

This file will look quite different because it's HTML. Don't panic. Simply Ctrl + F (i.e. the find feature) and search for the category that you want to put your User Guide in. You will see there are some sections that are not indented like the others. They are flush with the left side of the screen. **Do not change the indentation.** You can put markdown in these areas.

qubenix's avatar
qubenix committed
207
Once you've identified the non-indented area under the category you would like your User Guide to be under, you can use markdown to insert your link with the others in alphabetic order. `[TITLE OF USER GUIDE]({{site.baseurl}}/LINK-TO-USER-GUIDE.html)`. Please note that the file name in between the parentheses must be EXACTLY the same name as the permalink you made in step 5.3, but with a `.html` at the end instead of `.md` and the snippet `{{site.baseurl}}/` before the link.
D Sal's avatar
D Sal committed
208 209 210

In the event that you think your User Guide should be in a new Category that doesn't exist yet, contact rehrar to make one for you.

211 212
Repeat the above process for each language version of this index page INCLUDING THE template.

213
### 8. Build/Test
D Sal's avatar
D Sal committed
214 215
Build your website using `jekyll serve` if it's not rebuilding automatically and test that your link appears in the correct category and that it leads to your User Guide when clicked. Test your User Guide in the browser and contact rehrar if there are any bugs.

216
### 9. Submit Pull Request
D Sal's avatar
D Sal committed
217 218
You're all done. Submit a PR and wait for it to be reviewed and merged. Be sure to make any changes if requested.

219
## How to make a Moneropedia Entry
D Sal's avatar
D Sal committed
220

221
### 1. Make a Global file
D Sal's avatar
D Sal committed
222
Navigate to the /resources/moneropedia folder and make a new file. Be sure the file name has no spaces and the ending is .md
el00ruobuob's avatar
el00ruobuob committed
223
Fil this file with this exact content:
D Sal's avatar
D Sal committed
224 225 226
```
---
layout: moneropedia
el00ruobuob's avatar
el00ruobuob committed
227 228 229 230 231 232 233 234 235
---

@moneropedia_article

{% t global.lang_tag %}
{% tf resources/moneropedia/account.md %}

```

236
### 2. Make the localized File
el00ruobuob's avatar
el00ruobuob committed
237 238 239 240
Navigate to the /\_i18n/en/resources/moneropedia folder and make a new file. give it the same <name>.md than in previous step.
Start the file with the front Matter:
```
---
D Sal's avatar
D Sal committed
241 242 243 244 245 246
entry: "PUT THE NAME OF THE TERM HERE IN QUOTE, THIS IS HOW IT WILL SHOW UP ON THE LANDING PAGE"
terms: ["PUT", "TERMS", "HERE", "EXPLAINED", "BELOW"]
summary: "PUT SUMMARY OF YOUR ENTRY HERE IN QUOTES"
---
```

Dimitris Apostolou's avatar
Dimitris Apostolou committed
247
There are two things to highlight:  
el00ruobuob's avatar
el00ruobuob committed
248
The `terms:` section of the front matter can be filled with as many terms as you would like. This is how other Moneropedia entries will link to this page. You can link to other Moneropedia entries as well in your page by putting an ampersand before the term used, i.e. `@THE-TERM-USED`. This will make an automatic link in the Moneropedia entry to the referred term, replace the @term with the word used in that terms `entry:` area of the front matter, and on hover it will show the summary. How cool is that?  
Dimitris Apostolou's avatar
Dimitris Apostolou committed
249
The lines must not contain trailing whitespace, and it must be no blank lines added, otherwise the site with not build correctly.
D Sal's avatar
D Sal committed
250

251
### 3. Write
D Sal's avatar
D Sal committed
252 253
Write your Moneropedia entry. Remember that you can link to other Moneropedia entries using `@term-used-in-entry` as described above. Just go to the .md file of the Moneropedia entry you want to link to and use any of the terms in the `terms:` field of the front matter. Be sure to write whichever one you choose EXACTLY as shown and preceded by an ampersand.

254
### 4. Copy to other languages
el00ruobuob's avatar
el00ruobuob committed
255 256 257 258 259 260 261 262 263 264 265 266 267
Copy the file from the /\_i18n/en/resources/moneropedia folder to the other /\_i18n/<language>/resources/moneropedia folders and add the untranslated snippet at the same time just after the front matter, so it looks like:
```
---
entry: "PUT THE NAME OF THE TERM HERE IN QUOTE, THIS IS HOW IT WILL SHOW UP ON THE LANDING PAGE"
terms: ["PUT", "TERMS", "HERE", "EXPLAINED", "BELOW"]
summary: "PUT SUMMARY OF YOUR ENTRY HERE IN QUOTES"
---

{% include untranslated.html %}
```

If you want to translate in your native language, go to the 14.3.2 section below to read about specificities.

268
### 5. Build/Test
D Sal's avatar
D Sal committed
269 270
Build your website using `jekyll serve` if it's not rebuilding automatically and test check the link to your entry is appearing on the alphabetical list of Moneropedia entries and that it leads to your entry when clicked. Test your Moneropedia entry in the browser and contact rehrar if there are any bugs.

271
### 6. Submit Pull Request
D Sal's avatar
D Sal committed
272 273
You're all done. Submit a PR and wait for it to be reviewed and merged. Be sure to make any changes if requested.

274
## How to update the Team page
D Sal's avatar
D Sal committed
275 276 277

If you are acting on behalf of another individual, please make sure you get their permission first before adding them onto the Team page.

278
### 1. Change the .yml file
el00ruobuob's avatar
el00ruobuob committed
279
Navigate to the `/_data/` folder and open `team.yml`. You will notice a long list separated by main `-area:` tags.
D Sal's avatar
D Sal committed
280 281 282 283 284 285 286 287

**DO NOT MESS WITH THE FORMATTING OR INDENTATION OF ANYTHING OR JEKYLL WILL NOT BUILD PROPERLY!**

Find the area that you want to update and copy the code below:
```
- name:
  url:
```
288
Put the name or handle of the person in the `name` section and in the  `url:` section put the link to their GitHub or GitLab URL (it must have https:// at the beginning). If they have no GitHub, then you may leave it blank, it won't mess anything up.
D Sal's avatar
D Sal committed
289 290 291 292 293

**Make sure the indentation is EXACTLY the same as the other proposals in the area. If it's not the jekyll build WILL fail.**

Save the file.

294
### 2. Build/Test
D Sal's avatar
D Sal committed
295 296
Build your website using `jekyll serve` if it's not rebuilding automatically. If the build fails and you receive an error, you may have messed up somewhere in the `team.yml` file back in 8.1. Go back to that section and check the indentation. Yes, it's stupid. Yes, it has to be perfect.

297
If the build is successful, go to the Team page `/community/team/` and check to see that the contributor is showing up in the correct place. Click their GitHub or GitLab link (if applicable) and make sure it redirects correctly. Test the page and let rehrar know if there are any bugs.
D Sal's avatar
D Sal committed
298

299
### 3. Submit a Pull Request
D Sal's avatar
D Sal committed
300 301
You're all done. Submit a PR and wait for it to be reviewed and merged. Be sure to make any changes if requested.

302
## How to make an Event
D Sal's avatar
D Sal committed
303

304
### 1. Edit the .yml file
el00ruobuob's avatar
el00ruobuob committed
305
Navigate to the `/_data/` folder and open `events.yml`. You will notice a  list separated by hyphenated `-event` tags.
D Sal's avatar
D Sal committed
306 307 308 309 310 311 312 313 314 315 316 317 318 319 320

**DO NOT MESS WITH THE FORMATTING OR INDENTATION OF ANYTHING OR JEKYLL WILL NOT BUILD PROPERLY!**

Find the area that you want to update and copy the code below:
```
- event:
  where:
  when:
  description:
  link:
```
and paste it IN THE CHRONOLOGICAL ORDER that it will be in. So if there is an event happening before yours, make sure it is higher up than yours. If there is an event happening AFTER yours, make sure it is after your event.

Fill in the data as follows:
* `event:` The name of the event goes here as well as the date. The recommended format is: `Event Name - January 1st, 2000`
321
* `where:` Where the event will take place. Venue name and address are recommended.
D Sal's avatar
D Sal committed
322
* `when:` Date and time
323
* `description:` Description of the happenings of your event
D Sal's avatar
D Sal committed
324 325 326 327 328 329
* `link:` The website of your event (if applicable, this can be left blank and everything will be ok). This link must have http:// at the beginning if it is an external link.

**Make sure the indentation is EXACTLY the same as the other proposals in the area. If it's not the jekyll build WILL fail.**

Save the file.

330
### 2. Build/Test
D Sal's avatar
D Sal committed
331 332 333 334
Build your website using `jekyll serve` if it's not rebuilding automatically. If the build fails and you receive an error, you may have messed up somewhere in the `events.yml` file back in 9.1. Go back to that section and check the indentation. Yes, it's stupid. Yes, it has to be perfect.

If the build is successful, go to the Events page `/community/events/` and check to see that the event is showing up in the correct place. Click their Event url link (if applicable) and make sure it redirects correctly. Test the page and let rehrar know if there are any bugs.

335
### 3. Submit a Pull Request
D Sal's avatar
D Sal committed
336 337
You're all done. Submit a PR and wait for it to be reviewed and merged. Be sure to make any changes if requested.

338
## How to update the Roadmap
D Sal's avatar
D Sal committed
339

340
### 1. Edit the .yml file
el00ruobuob's avatar
el00ruobuob committed
341
Navigate to the `/_data/` folder and open `roadmap.yml`. You will notice a list separated by hyphenated `-year` tags.
D Sal's avatar
D Sal committed
342 343 344 345 346 347 348 349 350

**DO NOT MESS WITH THE FORMATTING OR INDENTATION OF ANYTHING OR JEKYLL WILL NOT BUILD PROPERLY!**

Find the year that you want to update and copy the code below:
```
- name:
  date:
  status:
```
351
and paste it in the correct year's `accomplishments:` section IN THE CHRONOLOGICAL ORDER that it will be in. So if there is a accomplishment that happened/is happening before the one you are inputting, make sure it is higher up than yours. If there is an accomplishment that happened/is happening AFTER yours, make sure it is after yours. If you don't have exact dates, just do your best to estimate.
D Sal's avatar
D Sal committed
352 353 354 355 356 357 358 359 360 361

Fill in the data as follows:
* `name:` The name of the accomplishment. Try to keep it short, a sentence or two at most.
* `date:` When the accomplishment happened (past) or when it is expected to happen (future)
* `status:` If the task is done, put `completed`, if the task is currently in the works put `ongoing`, and if work on the task has not yet started to your knowledge, but is expected to, put `upcoming`.

**Make sure the indentation is EXACTLY the same as the other proposals in the area. If it's not the jekyll build WILL fail.**

Save the file.

362
### 2. Build/Test
D Sal's avatar
D Sal committed
363 364 365 366
Build your website using `jekyll serve` if it's not rebuilding automatically. If the build fails and you receive an error, you may have messed up somewhere in the `roadmap.yml` file back in 10.1. Go back to that section and check the indentation. Yes, it's stupid. Yes, it has to be perfect.

If the build is successful, go to the Events page `/resources/roadmap/` and check to see that the newly added accomplishment is showing up in the correct place in the correct year. Test the page and let rehrar know if there are any bugs.

367
### 3. Submit a Pull Request
D Sal's avatar
D Sal committed
368 369
You're all done. Submit a PR and wait for it to be reviewed and merged. Be sure to make any changes if requested.

370
## How to add a new Merchant
D Sal's avatar
D Sal committed
371

372
### 1. Edit the .yml file
el00ruobuob's avatar
el00ruobuob committed
373
Navigate to the `/_data/` folder and open `merchants.yml`. You will notice a list separated by hyphenated `-category` tags.
D Sal's avatar
D Sal committed
374 375 376 377 378 379 380 381 382 383 384

**DO NOT MESS WITH THE FORMATTING OR INDENTATION OF ANYTHING OR JEKYLL WILL NOT BUILD PROPERLY!**

Find the category that best describes your business/service and copy the code below:
```
- name:
  url:
```
and paste it in the correct category under the `merchants:` section.

Fill in the data as follows:
385
* `name:` The name of the business/service.
D Sal's avatar
D Sal committed
386 387 388 389 390 391
* `url:` The external url of the business/service. This link must have http:// (or https://) at the beginning if it is an external link.

**Make sure the indentation is EXACTLY the same as the other proposals in the area. If it's not the jekyll build WILL fail.**

Save the file.

392
### 2. Build/Test
D Sal's avatar
D Sal committed
393 394 395 396
Build your website using `jekyll serve` if it's not rebuilding automatically. If the build fails and you receive an error, you may have messed up somewhere in the `merchants.yml` file back in 10.1. Go back to that section and check the indentation. Yes, it's stupid. Yes, it has to be perfect.

If the build is successful, go to the Merchants page `/community/merchants/` and check to see that the business is showing up in the correct category and that the link is redirecting correctly. Test the page and let rehrar know if there are any bugs.

397
### 3. Submit a Pull Request
D Sal's avatar
D Sal committed
398 399
You're all done. Submit a PR and wait for it to be reviewed and merged. Be sure to make any changes if requested.

400
## How to add a question to the FAQ
D Sal's avatar
D Sal committed
401

402
### 1. Copy/Paste Code
403
Navigate to the `/get-started/faq` folder and open the `index.md` file. Inside you will see HTML code, but you will see it is very repetitive.
D Sal's avatar
D Sal committed
404 405 406 407 408 409

Copy the code below:
```
<div class="tab">
    <input id="tab-CHANGETHIS" type="checkbox" name="tabs" class="accordian">
    <label for="tab-CHANGETHIS" class="accordian">CHANGE QUESTION</label>
el00ruobuob's avatar
el00ruobuob committed
410

D Sal's avatar
D Sal committed
411 412 413 414 415 416 417 418
<div class="tab-content" markdown="1">

CHANGE ANSWER

</div>

</div>
```
419
And paste it at the very bottom of the file (literally underneath everything else).
D Sal's avatar
D Sal committed
420 421 422 423 424 425 426 427 428 429 430

Now we're going to change just a couple of things. Find the section with:
```
<input id="tab-CHANGETHIS" type="checkbox" name="tabs" class="accordian">
<label for="tab-CHANGETHIS" class="accordian">CHANGE QUESTION</label>
```

and change the sections in between the quotes that say 'CHANGETHIS'. Leave the first part `tab-` alone. You can change it to anything really, as long as they are identical in the input and label, but it's good to see what number is on the last FAQ question (i.e. `tab-nine`) and make it the next number.

Now inside the label tag you're going to find where it says 'CHANGE QUESTION' and change it to the Question you want answered.

el00ruobuob's avatar
el00ruobuob committed
431
Lastly, find the words 'CHANGE ANSWER' and change it to the answer of your question.
D Sal's avatar
D Sal committed
432

el00ruobuob's avatar
el00ruobuob committed
433
**DO NOT MESS WITH THE INDENTATION HERE. The div that has `markdown=1` MUST be flush with the left side, the answer to the question must start flush with the left side, and the `</div>` MUST be flush with the left side.**
D Sal's avatar
D Sal committed
434

435
### 2. Build/Test
D Sal's avatar
D Sal committed
436 437
Build your website using `jekyll serve` if it's not rebuilding automatically. If the build is successful, go to the FAQ page `/get-started/faq/` and check to see that your question is showing up and, when clicked, the answer drops down. If not, check to make sure that the `id="tab-CHANGETHIS"` in the input and the `for="CHANGETHIS"` in the label are identical to each other. Test the page and let rehrar know if there are any bugs.

438
### 3. Submit a Pull Request
D Sal's avatar
D Sal committed
439 440
You're all done. Submit a PR and wait for it to be reviewed and merged. Be sure to make any changes if requested.

441
## How to add a publication to the Library
el00ruobuob's avatar
el00ruobuob committed
442

443
### 1. Add your file
el00ruobuob's avatar
el00ruobuob committed
444 445 446 447
Navigate to the `/library/` folder and drop your publication file here.

Please remind to minimize the size of your publication. For PDF, you'll find a large amount of service to compress your file with a minimal loss in quality.

448
### 2. Edit the .yml files
el00ruobuob's avatar
el00ruobuob committed
449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477
Navigate to the `/_i18n/` folder and open `en.yml`.

Go down until you find the `library` section. You will notice a list separated by hyphenated `-category` tags in a `books:` section.

**DO NOT MESS WITH THE FORMATTING OR INDENTATION OF ANYTHING OR JEKYLL WILL NOT BUILD PROPERLY!**

Find the category that best corresponds your publication and copy the code below:
```
- name: "<name>"
  file: "<filename>"
  abstract: >
    <abstract><br>
    <on multiple lines>
```
and paste it in the correct category under the `publications:` section.

For books, paste it in alphabetical order. For magazines, past it at the top.

Fill in the placeholders as follows:
* `<name>` The name of the publication, as it should be displayed.
* `<file>` The filename you have dropped in `/library/` folder, including extension.
* `<abstract>`,`<on multiple lines>` An abstract for your publication, formatted with html newlines `<br>`

**Make sure the indentation is EXACTLY the same as the other proposals in the area. If it's not the jekyll build WILL fail.**

Save the file.

open other `*.yml` files and copy the same code to it, in the exact same place.

478
### 3. Build/Test
el00ruobuob's avatar
el00ruobuob committed
479 480 481 482
Build your website using `jekyll serve` if it's not rebuilding automatically. If the build fails and you receive an error, you may have messed up somewhere in a `*.yml` file back in 13.1. Go back to that section and check the indentation. Yes, it's stupid. Yes, it has to be perfect.

If the build is successful, go to the Library page `/library/` and check to see that the publication is showing up in the correct category and that the link is downloading correctly. Test the page and let rehrar know if there are any bugs.

483
### 4. Submit a Pull Request
el00ruobuob's avatar
el00ruobuob committed
484 485
You're all done. Submit a PR and wait for it to be reviewed and merged. Be sure to make any changes if requested.

486
## Translations
487
In this section you'll find the info you need to translate a page and add a new translation, but keep in mind that Monero has a [Localization Workgroup](https://taiga.getmonero.org/project/erciccione-monero-localization/) who coordinate and give support to translators-volunteers. You can find an updated guide and an example of the workflow we use on our [Guide on Taiga](https://taiga.getmonero.org/project/erciccione-monero-localization/wiki/translating-monero-website) (frequently updated), also, for live support/request of infos, come chat on `#monero-translations` (Freenode/IRC, riot/matrix, MatterMost).
488

489 490 491
## How to translate a page

### 1. Quickstart
492 493 494 495 496 497
* Navigate to the correct language in the /i18n folder and find the page you wish to translate
* Click the file and translate the page, not touching any HTML or markdown.
* Remove `{% include untranslated.html %}` from the page
* Test/Build
* Submit PR

498
### 2. Naviate to correct file
499 500
Go to the /i18n folder and find the two letter code for the language you wish to translate for. Enter that folder and find the file you wish to translate. The filenames are all in English and MUST NOT BE CHANGED.

501
### 3. Translate the file
502 503
Here you can do your translation. Depending on the page, you may have to maneuver around some HTML or markdown. In general, anything between two tags (such as `<p>TRANSLATE THIS</p>`) should be fine. Testing is VERY important, so do NOT skip step 13.4. If during testing, the page appears different from the original English page (besides the translated text of course), you did something wrong and may have to start again.

504
#### 3.1. Notes for Moneropedia Entries
el00ruobuob's avatar
el00ruobuob committed
505 506 507 508 509 510
Moneropedia entries have two specificities:

* The Front Matter:  
Moneropedia Fron should be translated for both *entry:* and *summary:* elements. However, *terms:* should be extanded with their translation, leaving the English words **untouched**.
This is really important for compatibility purposes. With this, if a new guide is added to the site, an English term on the untranslated version of the guide in another language could be linked to the moneropedia article (of the same language).

Dimitris Apostolou's avatar
Dimitris Apostolou committed
511
* The old *untranslated* snippet must be removed, therefore the next section 14.4 is irrelevant here.
el00ruobuob's avatar
el00ruobuob committed
512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531

Finally, your entry should go from:
```
---
entry: "Entry name in English"
terms: ["English", "terms"]
summary: "English summary."
---

{% include untranslated.html %}
```
To:
```
---
entry: "Translated entry name"
terms: ["English", "terms", "translated", "terms"]
summary: "Translated summary."
---
```

532
### 4. set the 'translated' snippet to true
el00ruobuob's avatar
el00ruobuob committed
533
Somewhere on the page (usually the top) should be a snippet that says `{% include disclaimer.html translated="false" version=page.version %}`. Simply change this to `{% include disclaimer.html translated="true" version=page.version %}`. This will remove the orange bar from the bottom saying the page is untranslated.
534

535
### 5. Build/Test
536 537 538 539
Build your website using `jekyll serve` if it's not rebuilding automatically.

If the build is successful, go to the correct page in the correct language and check to see that everything is translated, and that the page looks identical to the original English page (besides the translated text). Test the page and let rehrar know if there are any bugs.

540
### 6. Submit a Pull Request
541 542
You're all done. Submit a PR and wait for it to be reviewed and merged. Be sure to make any changes if requested.

543
## How to add a new language
544 545
Whoo boy, this is the big one. Please follow all directions exactly.

546
### 1. \_config.yml file
el00ruobuob's avatar
el00ruobuob committed
547
Navigate to the root folder of the whole website and find the file labeled `_config.yml`. Open it and find the line that says `languages:`. Add your two letter language code (Google it if you don't know it) in between the brackets after the others already present. You will need to put a comma after the previous last one.
548 549 550 551 552 553 554

Example:
```
languages: ["en", "es", "NEW LANG HERE"]
```
Save and exit the file.

555
### 2. \_data folder
el00ruobuob's avatar
el00ruobuob committed
556
Navigate to the `_data/lang` folder and copy the `template` folder. Paste it into the same folder and the copy renamed to the two letter language code of the language you will be translated to.
557 558 559 560
**The template folder itself should still be there. It should not be renamed. There should be a new folder in addition to the ones that were already there.**

Translate the content of the files. Do not touch anything labeled `url`, and in the roadmap.yml ONLY translate the `name:` content.

561
### 3. \_i18n folder
el00ruobuob's avatar
el00ruobuob committed
562
Navigate to the \_i18n folder and duplicate the en.yml file. Rename the duplicate to the two letter language code of your language with a `.yml` at the end and change all sections marked 'translated: "yes"' to 'translated: "no"'. Change back to 'yes' once you have translated that section. Now duplicate the `en` folder and rename it with the correct language code.
563
**The original folder and yml file themselves should still be there. They should not be renamed. There should be a new folder and yml file in addition to the ones that were already there.**
564 565 566

Enter the .yml file and translate everything there.

567
### 4. Translate
568 569
If you will be translating the content, please refer to section 13.0 in this README for instructions on translating pages.

570
### 5. Build/Test
571 572
Build your website using `jekyll serve`. If the build is successful, navigate to any page on the site and check to make sure that your language is appearing in the dropdown for languages on both mobile and desktop.

573
### 6. Submit a Pull Request
574
You're all done. Submit a PR and wait for it to be reviewed and merged. Be sure to make any changes if requested.