Merge pull request consuldemocracy#122 from consul/markdown-lint

Apply markdown lint rules
rockandror · Apr 21, 2023 · 7d04792 · 7d04792
2 parents d5da917 + d00cd34
commit 7d04792
Show file tree

Hide file tree

Showing 48 changed files with 260 additions and 201 deletions.
diff --git a/.mdlrc b/.mdlrc
@@ -1 +1 @@
-rules "MD001", "MD002", "MD003", "MD004", "MD005", "MD006", "MD007", "MD008", "MD009", "MD010", "MD011", "MD012", "MD014", "MD015", "MD016", "MD017", "MD018", "MD019", "MD020", "MD021", "MD022", "MD023", "MD024", "MD025", "MD026", "MD027", "MD028", "MD029", "MD030", "MD031", "MD032", "MD033", "MD034", "MD035", "MD036", "MD037", "MD038", "MD039", "MD040", "MD041"
+rules "MD001", "MD002", "MD003", "MD004", "MD005", "MD006", "MD007", "MD008", "MD009", "MD010", "MD011", "MD012", "MD014", "MD015", "MD016", "MD017", "MD018", "MD019", "MD020", "MD021", "MD022", "MD023", "MD025", "MD026", "MD027", "MD028", "MD030", "MD031", "MD032", "MD033", "MD034", "MD035", "MD036", "MD037", "MD038", "MD039", "MD040", "MD041"
diff --git a/README.md b/README.md
@@ -67,7 +67,7 @@ But for some actions like voting, you will need a verified user, the seeds file
 
 ## Documentation
 
-You can find this project documentation at https://github.com/consul/docs.
+You can find this project documentation at <https://github.com/consul/docs>.
 
 ## License
 

diff --git a/SUMMARY.md b/SUMMARY.md
@@ -30,9 +30,9 @@
 
 * [Customization](en/customization/customization.md)
   * [Introduction](en/customization/introduction.md)
-  * [Texts & Translations](en/customization/translations.md)
+  * [Translations and Texts](en/customization/translations.md)
   * [Images](en/customization/images.md)
-  * [Views & Styles](en/customization/views_and_styles.md)
+  * [Views and Styles](en/customization/views_and_styles.md)
   * [Javascript](en/customization/javascript.md)
   * [Models](en/customization/models.md)
   * [Components](en/customization/components.md)
@@ -83,9 +83,9 @@
 
 * [Personalización](es/customization/customization.md)
   * [Introducción](es/customization/introduction.md)
-  * [Textos & Traducciones](es/customization/translations.md)
+  * [Traducciones y Textos](es/customization/translations.md)
   * [Imágenes](es/customization/images.md)
-  * [Vistas & Estilos](es/customization/views_and_styles.md)
+  * [Vistas y Estilos](es/customization/views_and_styles.md)
   * [Javascript](es/customization/javascript.md)
   * [Modelos](es/customization/models.md)
   * [Componentes](es/customization/components.md)

diff --git a/en/README.md b/en/README.md
@@ -67,7 +67,7 @@ But for some actions like voting, you will need a verified user, the seeds file
 
 ## Documentation
 
-You can find this project documentation at https://github.com/consul/docs.
+You can find this project documentation at <https://github.com/consul/docs>.
 
 ## License
 

diff --git a/en/customization/customization.md b/en/customization/customization.md
@@ -1,9 +1,9 @@
 # Customization
 
 * [Introduction](introduction.md)
-* [Texts & Translations](translations.md)
+* [Translations and Texts](translations.md)
 * [Images](images.md)
-* [Views & Styles](views_and_styles.md)
+* [Views and Styles](views_and_styles.md)
 * [Javascript](javascript.md)
 * [Models](models.md)
 * [Components](components.md)

diff --git a/en/customization/images.md b/en/customization/images.md
@@ -14,4 +14,4 @@ If you want to overwrite any image, firstly you need to find out the filename, a
 
 You'll find the city map at [`/app/assets/images/map.jpg`](https://github.com/consul/consul/blob/master/app/assets/images/map.jpg), just replace it with an image of your cities districts ([example](https://github.com/ayuntamientomadrid/consul/blob/master/app/assets/images/map.jpg)).
 
-Afterwards we recommend you to use an online tool like http://imagemap-generator.dariodomi.de/ or https://www.image-map.net/ to generate the html coordinates to be able to generate a [image-map](https://www.w3schools.com/tags/tag_map.asp) for each of the districts. Those coordinates should be introduced on the respective Geozones at the admin geozones panel (`/admin/geozones`).
+Afterwards we recommend you to use an online tool like <http://imagemap-generator.dariodomi.de/> or <https://www.image-map.net/> to generate the html coordinates to be able to generate a [image-map](https://www.w3schools.com/tags/tag_map.asp) for each of the districts. Those coordinates should be introduced on the respective Geozones at the admin geozones panel (`/admin/geozones`).
diff --git a/en/customization/introduction.md b/en/customization/introduction.md
@@ -28,67 +28,80 @@ The aim of this service is to be able to offer all the dynamic contents of the a
 
 When a user visits a page with a language where there is untranslated content, they will have a button to request the translation of all the content. This content will be sent to an automatic translator (in this case [Microsoft TranslatorText](https://azure.microsoft.com/en-us/products/cognitive-services/translator/)) and as soon as the response is obtained, all these translations will be available to any user.
 
-#### Getting started
+### Getting started
+
 In order to use this functionality, the following steps are necessary:
+
 1. Have an api key to connect to the translation service. For this we need an [Azure account](https://azure.microsoft.com/en-us/)
 1. Once you are logged into the Azure portal, subscribe to the Translator in Cognitive Service.
 1. Once you have subscribed to the Translator Text service, you will have access to 2 api keys in the section **Resource Management > Keys and Endpoint** that will be necessary for the configuration of the translation service in your application.
 
-#### Configuration
+### Configuration
+
 To activate the translation service in your application you must complete the following steps:
 
-##### Add api key in the application
+#### Add api key in the application
+
 In the previous section we have commented that once subscribed to the translation service we have 2 api keys. To configure the service correctly in our application we must add one of the two api keys in the file `secrets.yml` in section `apis:` with the key `microsoft_api_key` as we can see in the following image:
 
 ![Add api key to secrets](../../img/translations/remote_translations/add-api-key-to-secrets.png)
 
-##### Activate module
+#### Activate module
+
 Once we have the new key in the `secrets.yml` we can now proceed to activate the module. To activate the functionality you must follow 2 steps:
+
 1. Execute the following command `bin/rake settings:create_remote_translations_setting RAILS_ENV=production`
 1. Accessing through the administration panel of your application to the section **Configuración > Funcionalidades** and activate module **Traducciones Remotas** as shown below:
-![Active remote translations](../../img/translations/remote_translations/active-remote-translations-en.png)
+  ![Active remote translations](../../img/translations/remote_translations/active-remote-translations-en.png)
+
+### Use Cases
 
-#### Use Cases
 Once we have the api key in our `secrets.yml` and the activated module, users will already be able to use the functionality.
 We attach some screenshots of how the application interacts with our users:
+
 * When a user visits a page in a language without translated content, an informative text will appear at the top of the page and a button to request the translation. (**Note:** *If user visit page with a language not supported by the translation service, no text or translation button will be displayed. See section: Available languages for remote translation*)
-![Display text and button](../../img/translations/remote_translations/display-text-and-button-en.png)
+  ![Display text and button](../../img/translations/remote_translations/display-text-and-button-en.png)
 
 * Once the user click the `Translate page` button, the translations are enqueued and the page is reloaded with a notice (*Informing that the translations have been requested correctly*) and an informative text in the header (*explaining when you will be able to see these translations*).
-![Display notice and text after enqueued translations](../../img/translations/remote_translations/display-notice-and-text-after-enqueued-en.png)
+  ![Display notice and text after enqueued translations](../../img/translations/remote_translations/display-notice-and-text-after-enqueued-en.png)
 
 * If an user visit a page that does not have translations but have already been requested by another user. The application will not show you the translate button, but an informative text in the header (*explaining when you will be able to see these translations*).
-![Display text explaining that translations are pending](../../img/translations/remote_translations/display-text-translations-pending-en.png)
+  ![Display text explaining that translations are pending](../../img/translations/remote_translations/display-text-translations-pending-en.png)
 
 * The translation request, response processing and data saving are delegated to `Delayed Jobs` and as soon as they are processed, the user will be able to read them after page refresh.
-![Display translated content](../../img/translations/remote_translations/display-translated-content-en.png)
+  ![Display translated content](../../img/translations/remote_translations/display-translated-content-en.png)
 
+### Available languages for remote translation
 
-#### Available languages for remote translation
 Currently these are all the [available languages](https://api.cognitive.microsofttranslator.com/languages?api-version=3.0) in the translation service:
+
 ```yml
 ["af", "am", "ar", "as", "az", "ba", "bg", "bn", "bo", "bs", "ca", "cs", "cy", "da", "de", "dv", "el", "en", "es", "et", "eu", "fa", "fi", "fil", "fj", "fo", "fr", "fr-CA", "ga", "gl", "gu", "ha", "he", "hi", "hr", "hsb", "ht", "hu", "hy", "id", "ig", "ikt", "is", "it", "iu", "iu-Latn", "ja", "ka", "kk", "km", "kmr", "kn", "ko", "ku", "ky", "ln", "lo", "lt", "lug", "lv", "lzh", "mg", "mi", "mk", "ml", "mn-Cyrl", "mn-Mong", "mr", "ms", "mt", "mww", "my", "nb", "ne", "nl", "nso", "nya", "or", "otq", "pa", "pl", "prs", "ps", "pt", "pt-PT", "ro", "ru", "run", "rw", "sk", "sl", "sm", "sn", "so", "sq", "sr-Cyrl", "sr-Latn", "st", "sv", "sw", "ta", "te", "th", "ti", "tk", "tlh-Latn", "tlh-Piqd", "tn", "to", "tr", "tt", "ty", "ug", "uk", "ur", "uz", "vi", "xh", "yo", "yua", "yue", "zh-Hans", "zh-Hant", "zu"]
 ```
+
 Of all the languages that Consul currently has defined (`available_locales`) in `config/application.rb` the only one that is not listed above and therefore no translation service is offered is Valencian `["val"]`.
 
-#### Pricing
+### Pricing
+
 The translation service used has the most competitive [pricing](https://azure.microsoft.com/en-us/pricing/details/cognitive-services/translator/).
 The price for each 1 Million characters translated is $10 and there is no fixed cost per month.
 
 Although technical measures have been taken to prevent misuse of this service, we recommend the creation of Alerts offered by Azure so that an Administrator can be notified in the event of detecting unusual use of the service. This service has a cost of $0.10 per month.
 
 To create an Alert in Azure we must follow the following steps:
+
 1. Sign in to the **Azure Portal**.
 1. Access the **Translator** service created earlier.
 1. Go to **Monitoring > Alerts** in the side menu:
-  1. Go to **Create alert rule**.
-  1. In **Select a signal** select `Text Characters Translated`.
-  1. Once selected we must define the logic of the Alert to suit our needs. Ex: Fill "Operator" field with "Greater than" option, fill "Aggregation type" field with "Total" option and fill "Threshold value" field with the number of characters we consider should be translated before being notified. In this section you can also set the time period and frequency of evaluation.
-  1. In order to be notified we have to create an **Action Group** and associate it with this Alert we're creating. To do this, access the button **Create** and fill out the form. As you can see there are different types of actions, we must select **Email/SMS/Push/Voice** and configure the option that we consider convenient according to our needs.
-  1. Once this group of actions has been created, it is directly associated with the rule we are creating.
-  1. Finally, all you have to do is add a name and click on the **Review + create**
-
-#### Add a new translation service
+   1. Go to **Create alert rule**.
+   1. In **Select a signal** select `Text Characters Translated`.
+   1. Once selected we must define the logic of the Alert to suit our needs. Ex: Fill "Operator" field with "Greater than" option, fill "Aggregation type" field with "Total" option and fill "Threshold value" field with the number of characters we consider should be translated before being notified. In this section you can also set the time period and frequency of evaluation.
+   1. In order to be notified we have to create an **Action Group** and associate it with this Alert we're creating. To do this, access the button **Create** and fill out the form. As you can see there are different types of actions, we must select **Email/SMS/Push/Voice** and configure the option that we consider convenient according to our needs.
+   1. Once this group of actions has been created, it is directly associated with the rule we are creating.
+   1. Finally, all you have to do is add a name and click on the **Review + create**
+
+### Add a new translation service
+
 If you want to integrate more translation services for any reason (new translation service appears, you want to change to include languages that are currently not supported, etc.) the code is ready to be added.
 This is made possible by the `RemoteTranslations::Caller` class which is an intermediate layer between untranslated content management and the currently used Microsoft Translation Client.
 A good solution for adding another translation service would be to replace the call to the `MicrosoftTranslateClient` in the `translations` method of `RemoteTranslations::Caller` with the new service implemented.
@@ -106,25 +119,27 @@ class RemoteTranslationsCaller
   ...
 
 end
-```   
+```
 
 ## Translation interface
 
 The aim of this feature is to allow users the introduction of dynamic contents in many languages at the same time. From the administration panel you can activate or deactivate it. If you deactivate this feature (default configuration) users will be able to enter one single translation.
 
-#### Enable module
+### Enable module
+
 To activate this feature you must follow 2 steps:
+
 1. Execute the following command `bin/rake settings:create_translation_interface_setting RAILS_ENV=production` (This is only required for already existing intallations, for new consul installations this step is not needed).
 2. Accessing as administrator user to the administration panel of your Consul application to the section **Configuration > Features** and activating the feature called **Translation Interface** as you can see next:
-![Active interface translations](../../img/translations/interface_translations/active-interface-translations-en.png)
+  ![Active interface translations](../../img/translations/interface_translations/active-interface-translations-en.png)
 
-#### Use Cases
+### Use Cases
 
 * When the translation interface is active:
-As you can see in the image below translation interface has two selectors, the first one "Select language" is to switch between enabled languages and the second one "Add language" is to add new languages to the form. Translatable fields appears with a blue background to facilitate users to distinguish between translatable and not translatable fields. Additionally interface provides a link `Remove language` to delete the current language shown at "Select language". If a user accidentally removes a translation he can recover it re-adding it to the form.
-This feature is visible during creation and edition of translatable resources.
-![Translations interface enabled](../../img/translations/interface_translations/translations-interface-enabled-en.png)
+  As you can see in the image below translation interface has two selectors, the firt one "Select language" is to switch between enabled languages and the second one "Add language" is to add new languages to the form. Translatable fields appears with a blue background to facilitate users to distinguish between translatable and not translatable fields. Additionally interface provides a link `Remove language` to delete the current language shown at "Select language". If a user accidentally removes a translation he can recover it re-adding it to the form.
+  This feature is visible during creation and edition of translatable resources.
+  ![Translations inteface enabled](../../img/translations/interface_translations/translations-interface-enabled-en.png)
 
 * When the translation interface is disabled:
-When this feature is deactivated users will see standard forms without translation interface and without translation highlight.
-![Translations interface enabled](../../img/translations/interface_translations/translations-interface-disabled-en.png)
+  When this feature is deactivated users will see standard forms without translation interface and without translation highlight.
+  ![Translations inteface enabled](../../img/translations/interface_translations/translations-interface-disabled-en.png)
diff --git a/en/customization/translations.md b/en/customization/translations.md
@@ -1,4 +1,6 @@
-# Translations
+# Translations and Texts
+
+## Translations
 
 Currently, CONSUL is totally or partially translated to multiple languages. You can find the translations at the [Crowdin project](https://crowdin.com/project/consul).
 
@@ -8,7 +10,7 @@ If your language isn't already present in the Crowdin project, please [open an i
 
 If you want to check existing translations of the user-facing texts you can find them organized in YML files under `config/locales/` folder. Take a look at the official Ruby on Rails [internationalization guide](http://guides.rubyonrails.org/i18n.html) to better understand the translations system.
 
-# Custom Texts
+## Custom Texts
 
 Since CONSUL is always evolving with new features, and in order to make your fork easier to be updated, we strongly recommend translation files not to be modified, but instead "overwritten" with custom translation files in case a text needs to be customized for you.
 
@@ -29,7 +31,7 @@ es:
 
 In order to customize it, you should create a new file `config/locales/custom/es/general.yml` with just that content, and change "Ayuntamiento de Madrid" with our organization name. We strongly recommend to make copies from `config/locales/` and modify or delete the lines as needed to keep the indentation structure and avoid issues.
 
-# Maintaining your Custom Texts & Languages
+## Maintaining your Custom Texts & Languages
 
 CONSUL has the [i18n-tasks](https://github.com/glebm/i18n-tasks) gem, it's an awesome helping tool to manage i18n translations. Just check `i18n-tasks health` for a nice report.
 

diff --git a/en/customization/views_and_styles.md b/en/customization/views_and_styles.md
@@ -1,8 +1,10 @@
-# Views (HTML)
+# Views and Styles
+
+## Views (HTML)
 
 If you want to change any page HTML  you can just find the correct file under the `app/views` folder and put a copy at `app/views/custom` keeping as well any sub-folder structure, and then apply your customizations. For example if you want to customize `app/views/pages/conditions.html` you'll have to make a copy at `app/views/custom/pages/conditions.html.erb` (note the `pages` subdirectory).
 
-# CSS Styles with SASS
+## CSS Styles with SASS
 
 In order to make changes to any CSS selector (custom style sheets), you can add them directly at `app/assets/stylesheets/custom.scss`. For example to change the header color (`.top-links`) you can just add: