This README here to walk you through everything you need to know to make changes, edits, or even completely new pages for the new getJudEcoin.org website. It'll definitely be a bit of a ride, so strap yourself in. Feel free to skip down to a relevant section if you already know what you need.
If you need support about something related to the website, please join #JudEcoin-site Freenode/IRC
-
Jekyll: getJudEcoin.org is made using a simple, static website generator called Jekyll. You will need it installed on your system to test any changes that you made. Follow the instructions on the website to get up and going:
- Install Ruby dependencies as suggested in the Jekyll documentation
- Install Bundler:
gem install bundler - Install Jekyll with all dependencies (run from the project directory):
bundle
-
GitHub/GitLab: Pretty much everything in JudEcoin is hosted on GitHub uses Git as the primary version control system. If you're not familiar with how to use Git, you can check out this tutorial 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 GitHub and fork the JudEcoin Website repository.
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:
- Navigate to your local
JudEcoin-siterepository. - Serve the website:
bundle exec jekyll serve. If you want, you can speedup this process by loading only the last blog post instead of all of them. Simply add--limit_posts 1to the command above. The resulting command will bebundle exec jekyll serve --limit_posts 1. - Open a browser and go to http://127.0.0.1:4000.
- If all went well, you should see the JudEcoin website and you're ready to make changes.
The average Judecoin user that will want to contribute to the website should probably start looking for issues labelled ⛑️ contributor needed or making blog posts, user guides or JudEcoinpedia 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 a web developer and would like to make large macro-level changes, it would be best to open an issue first or to get in contact with the developers on #JudEcoin-site (IRC/Freenode, MatterMost, Matrix).
This website is completely open-source however and anything and everything is available for changing should the community deem it necessary.
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.
A few random points of note:
- After a discussion, the community decided to include only open source wallets in the 'Downloads' section of the website. Requests to add closed source wallets to that page will be rejected.
- Listing merchants on the 'Merchants' page is at our discretion and acceptance shouldn't be assumed.
- All external links must have
https://in front of them or they will not redirect properly. - If you want to add a new page to the navigation, you should go to ALL LANGUAGES in the
_data/langfolder and add the page. - 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.
This website is available natively on Tor. The onion address is in _includes/onion.html and a signed document containing the same address is in /onion.txt. The address in these 2 files must always match. The onion.txt files also includes the onion address of the 'downloads' subdomain.
If you want to post getJudEcoin's onion address somewhere on the website, don't simply write it, instead include it using {% include onion.html %}. This avoids problems with typos and allow us top change the address only in one file if necessary.
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.
When a pull request suggesting changes is opened, it will be merged only once it will be reviewed (with some exceptions, like binaries and hashes updates). The process to review a PR is simple:
- Go through the suggested changes and check that everything is fine and nothing is broken. We have multiple tools that make this process easier: Netlify's previews, which will show a preview of how the website will look like once the PR is merged; GitHub's checks, which will try to build the PR and will say if there were errors during the process.
- if you think something should be changed, comment on the interested lines, stating clearly what changes you suggest and why. GitHub gives a set of useful tools to make code review easier for both authors and reviewers.
- When you think the PR is ready to be merged, use GitHub's native "Approve" option, or write a comment explicitly stating your approval. Some common ways to approve a PR is by writing: ACK/uTACK, Reviewed and LGTM (Let's Get This Merged). Doesn't matter what wording you use, just make your approval clear.
- In the case you wish a PR doesn't get merged for some reason, make it known by using clear wording. A common way to show disapproval is by writing NACK (Not Acknowledged). NACKing a PR should be accompanied by a detailed explanation of why that PR should be refused.
Some pull requests may be labelled Needs Review, these PR are prioritary and should be reviewed as soon as possible.
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. To keep track of those changes, the user guides (but not the developer guides) are versioned using a snippet at the top of each localized (_i18n/en/resources/*-guides) file:
{% include disclaimer.html translated="no" translationOutdated="no" %}
This snippet is responsible for keeping track of the language version. If the guide is translated, change translated="no" to translated="yes". if the page is translated, but something changed in the original guide in English, change translationOutdated="no" to translationOutdated="yes".
The based version (English version) is however also tracked in the Front Matter from the /resources/user-guides/ directory file:
outdated: False
If the guide is outdated, simply change False into True.
When you update a guide, you are responsible for updating this version tracking in every file involved in your update. Don't be afraid to ask for help if the process is not clear to you.
The screenshots of all user guides are in /img/user-guides/LANG. Where LANG can be any of the languages supported by GetJudEcoin. By default, all localized versions of the website will use the English version of the screenshots, see the translations section for info about translating screenshots.
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. Take a look at the other posts to get an idea of how to name yours
---
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
---
If you want to add a personalized picture to a blog post that will show as logo on social networks, add image: /blog/assets/$FOLDER/$IMAGE to the front matter. Where $FOLDER is the name of the folder you created to contain the image related to your blog post and $IMAGE is the name of the image.
After the front matter is finished you are free to write the remainder of your blog post in markdown.
- Create file in /resources/user-guides with an .md ending and no spaces in filename.
- Create file in /_i18n/en/resources/user-guides with the exact same filename as above ending in .md
- Write User Guide
- Add versioning snippet
- Copy User Guide file to ALL LANGUAGES in /_i18n/[ALL LANGUAGES]/resources/user-guides
- set translation to false in the snippet the top of each language version of your User Guide, except the original language
- 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
- Test/Build
- Submit PR
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
---
layout: user-guide
title: TITLE OF YOUR USER GUIDE
permalink: /resources/user-guides/NAME-OF-FILE-GOES-HERE.html
outdated: False
---
{% tf resources/user-guides/NAME-OF-FILE-GOES-HERE.md %}
Copy this exactly and merely change the files names where indicated.
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.
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. There should be NO front matter on this file.
Add the snippet monitoring the status of the translations at the top of your guide:
{% include disclaimer.html translated="no" translationOutdated="no" %}
If you are copying the structure of another guide, the snippet will be already there with the default value (no and no. Meaning the guide is not translated)
Copy your file and navigate to each language file in the /i18n folder. In each language folder 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.
As you paste into each folder, open up the file and make sure the snippet at the top of the file is correct:
{% include disclaimer.html translated="no" translationOutdated="no" %}.
In the /_i18n/[ORIGINAL LANGUAGE OF USER GUIDE]/resources/user-guides folder, find the file labeled index.md and open it.
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.
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.
In the event that you think your User Guide should be in a new Category that doesn't exist yet, contact the Website workgroup.
Repeat the above process for each language version of this index page.
Navigate to the /resources/JudEcoinpedia folder and make a new file. Be sure the file name has no spaces and the ending is .md Fill this file with this exact content:
---
layout: JudEcoinpedia
title: titles.JudEcoinpedia
entry: JudEcoinpedia.entries.ENTRY
---
@JudEcoinpedia_article
{% t global.lang_tag %}
{% tf resources/JudEcoinpedia/account.md %}
Where ENTRY is a one word identifier for the title/name of your JudEcoinpedia entry. For example, if you are adding a new JudEcoinpedia entry called "Daemon", it can be JudEcoinpedia.entries.daemon.
Navigate to the /_i18n/en/resources/JudEcoinpedia folder and make a new file. give it the same .md than in previous step. Start the file with the front Matter:
---
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"
---
There are two things to highlight:
The terms: section of the front matter can be filled with as many terms as you would like. This is how other JudEcoinpedia entries will link to this page. You can link to other JudEcoinpedia 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 JudEcoinpedia 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?
The lines must not contain trailing whitespace, and it must be no blank lines added, otherwise the site with not build correctly.
Write your JudEcoinpedia entry. Remember that you can link to other JudEcoinpedia entries using @term-used-in-entry as described above. Just go to the .md file of the JudEcoinpedia 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.
Copy the file from the /_i18n/en/resources/JudEcoinpedia folder to the other /_i18n//resources/JudEcoinpedia 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 disclaimer.html translated="no" translationOutdated="no" %}
Now you need to add the title of the page to the _18n/en.yml file. It must be in the JudEcoinpedia section and must be the same as the ENTRY you added early in the /resources/JudEcoinpedia folder (JudEcoinpedia.entries.ENTRY). Keeping as example a JudEcoinpedia called "Daemon", you have to add in the JudEcoinpedia block daemon: Daemon.
The page is composed by boxes, each containing a workgroup. Just make sure to copy the structure from the preceeding box and paste it right after it.
Note that the class of the div which forms the box is right/left half col-lg-6 col-md-6 col-sm-12 col-xs-12. Make sure to choose left or right according to the position you want the box to appear in.
The file containing the structure of the roadmap is in /resources/roadmap/index.md.
If you want to update the roadmap, you'll probably want to add a new entry (under an existing year+month) or a new entry under a new month.
A new entry can be added using HTML lists:
<li class="STATUS">{% t roadmap.KEY %}</li>
Where STATUS can be:
completedfor completed milestonesongoingfor milestones currently being worked onupcomingfor milestones not yet completed or in progress
If an entry is completed, a green tick simble will be displayed on its left. if it's ongoing a roadwork sign and upcoming a compass.
KEY is the key used in the _i18n/LANG.yml file, in the roadmap section. If you are adding a new entry, you only need to add the key and its contained text in the _i18n/en.yml file. Weblate, the localization platform, will deal with making the string available for translators and then add it to all languages.
If you need to add a month, add <h3 id="months">{% t roadmap.MONTH %}</h3> above your roadmap entry. MONTH is one of the 12 months, you'll find the list in the _18n/en.yml file. In the roadmap section.
The roadmap can be translated on Weblate on Weblate.
Navigate to the /_data/ folder and open merchants.yml. You will notice a list separated by hyphenated -category tags.
Find the category that best describes your business/service and copy the code below, making sure you are keeping the alphabetic order consistent:
- name:
url:
and paste it in the correct category under the merchants: section.
Fill in the data as follows:
name:The name of the business/service.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.
The structure of the FAQ is a bit more complex than it used to be and contains anchors, variables and a TOC. A step by step guide would be too complex to follow. A basic knowledge of HTML is necessary to edit the page. If you wish to add a new FAQ please open an issue in the repository or/and contact the Website workgroup.
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.
Navigate to the library folder and open the index.md file. Look for the appropriate section for your publication (books or magazines) and under the last entry add yours, using the same structure as the other entries:
<h3><a href="LINK-TO-PUBLICATION">NAME</a></h3>
<p>{% t library.PLACEHOLDER-NAME %}</p>
Where LINK-TO-PUBLICATION is the URL of the actual publication. If it's a resource external to GetJudEcoin, simply add the URL (for example https://masteringJudEcoin.com/free-download.html). If you uploaded the file in the /library folder as explained in step 1, use this structure: {{ site.baseurl_root }}/library/NAME-FILE.
PLACEHOLDER-NAME needs to be a placeholder that will be added in the _18n/en.yml file, under the library category, as explained in the next step.
After you found the library category, add your placeholder and value after the last entry of the list. For example: mypublication: "This is the description of my publication". In this example mypublication is the placeholder and needs to be also added to the entry in index.md, the result will be <p>{% t library.mypublication %}</p> and the value contained in the placeholder will be correctly displayed.
Save the changes.
This repository is licensed under the BSD 3-Clause "New" or "Revised" License.
All emojis designed by OpenMoji – the open-source emoji and icon project. License: CC BY-SA 4.0