decidim 0.26.0 → 0.27.0.rc1

data/docs/modules/configure/pages/index.adoc

@@ -2,6 +2,46 @@
 
 Decidim is a Ruby on Rails library, and as such we try to follow their conventions. Please read https://guides.rubyonrails.org/configuring.html[Configuring Rails Applications].
 
+Decidim is also a command line executable capable of generating your own Decidim installation.
+
+Install it as:
+
+[source,console]
+----
+gem install decidim
+----
+
+For a simple, bare application, just run:
+
+[source,console]
+----
+decidim my_decidim_application
+----
+
+However you can take advantage of the optional flags to automatically configure some aspects of the application.
+Check the available options using the `--help` modifier:
+
+[source,console]
+----
+decidim --help
+----
+
+For instance, if you are planing to use some external cloud storage service (such as S3), create a Decidim application using the `--storage` modifier:
+
+[source,console]
+----
+decidim --storage s3 my_decidim_application
+----
+
+It is also recommended to use a proper Job Queue processor such as `sidekiq` or `delayed_job`. The `--queue` modifier allows you to generate a Decidim Application with a proper Sidekiq configuration (DelayedJob is not supported yet, PR wellcomed, but you can easily just follow the https://github.com/collectiveidea/delayed_job[official instructions]):
+
+[source,console]
+----
+decidim --queue sidekiq my_decidim_application
+----
+
+Then make use of the related xref:configure:environment_variables.adoc[Environment Variables] to configure your particular provider.
+
 Just as a reminder, these files are important:
 
 * config/database.yml

data/docs/modules/configure/pages/initializer.adoc

@@ -1,8 +1,12 @@
 = Initializer
 
-There are some settings that you'll need to change in the `config/initializer/decidim.rb` file.
+There are some settings that you'll need to change in the `config/initializer/decidim.rb` file. We recommend that, whenever it is possible, you use xref:configure:environment_variables.adoc[Environment Variables], as just cleaner and easier to work with.
 
-This is where you can change the behaviour defined on the diferent components (most notably from `decidim-core`).
+If you need to add special logic or if you feel more comfortable working with Ruby code instead of Environment Variables, then you can of course do all the changes that you need directly in the initializer file. Take into account that this file could be published in a Version Control System (like `git`) so you should be careful with the secrets/API keys that you add here.
+
+Remember to restart your server when making changes in this file.
+
+This is where you can change the behaviour defined on the different components (most notably from `decidim-core`).
 
 After making changes to this file you'll need to also restart your application server.
 
@@ -62,7 +66,7 @@ this value for that specific organization.
 == Content Processors
 
 Defines a list of custom content processors. They are used to parse and
-render specific tags inside some user-provided content. Check the xref:develop:content_processor.adoc[Content Processor]
+render specific tags inside some user-provided content. Check the xref:develop:content_processors.adoc[Content Processor]
 docs for more info.
 
 [source,ruby]
@@ -97,7 +101,7 @@ Please refer to:
 
 == Geocoder configuration
 
-Allows to make geographical mapping in some components, like Proposals or Meetings. It must be configured against a OpenStreetMap provider. See xref:services:geocoder.adoc[Geocoder service documentation].
+Allows to make geographical mapping in some components, like Proposals or Meetings. It must be configured against a OpenStreetMap provider. See xref:services:maps.adoc[Geocoder service documentation].
 
 [source,ruby]
 ....
@@ -109,7 +113,7 @@ Allows to make geographical mapping in some components, like Proposals or Meetin
 
 == Custom resource reference
 
-Custom resource reference generator method. See the See xref:admin:system_panel.adoc[System panel docs] for more information.
+Custom resource reference generator method. See the See xref:admin:system.adoc[System panel docs] for more information.
 
 [source,ruby]
 ....
@@ -155,7 +159,7 @@ Mind that this depends on your environment, for instance you could also need to
 
 === User avatar file size
 
-  # The maximum file size for a user avatar
+The maximum file size for a user avatar
 
 Mind that this depends on your environment, for instance you could also need to change your web server configuration (nginx, apache, etc).
 
@@ -200,13 +204,13 @@ Allow organizations admins to track newsletter links, trough UTMs. See https://e
   config.track_newsletter_links = true
 ....
 
-== Data portability expiry time
+== Download your data expiry time
 
-Amount of time that the data portability files will be available in the server.
+Amount of time that the download your data files will be available in the server.
 
 [source,ruby]
 ....
-  config.data_portability_expiry_time = 7.days
+  config.download_your_data_expiry_time = 7.days
 ....
 
 == Throttling settings
@@ -257,7 +261,7 @@ If not set, it will be ignored.
 == SMS gateway configuration
 
 If you want to verify your users by sending a verification code via
-SMS you need to provide a SMS gateway service class.
+xref:services:sms.adoc[SMS] you need to provide a SMS gateway service class.
 
 An example class would be something like:
 
@@ -289,7 +293,7 @@ Used by `decidim-initiatives`.
 
 Provide a class to generate a timestamp for a document. The instances of
 this class are initialized with a hash containing the :document key with
-the document to be timestamped as value. The istances respond to a
+the document to be timestamped as value. The instances respond to a
 timestamp public method with the timestamp.
 
 An example class would be something like:
@@ -358,6 +362,37 @@ xref:services:etherpad.adoc[Etherpad's Decidim docs] in order to set it up.
   }
 ....
 
+==  Machine Translation Configuration
+
+To enable machine translations you need to enable the service and specify the class used for translation (this usually is the one contacting an external API from a 3d party service that actually translates the string).
+
+[source,ruby]
+....
+  config.enable_machine_translations = false
+  config.machine_translation_service = "MyTranslationService"
+....
+
+An example class would be something like:
+
+[source,ruby]
+....
+  class MyTranslationService
+    attr_reader :text, :original_locale, :target_locale
+
+    def initialize(text, original_locale, target_locale)
+      @text = text
+      @original_locale = original_locale
+      @target_locale = target_locale
+    end
+
+    def translate
+      Actual code to translate the text
+    end
+  end
+....
+
+See xref:develop:machine_translations.adoc[Machine Translations] for more information about how it works and how to set it up.
+
 == Default CSV column separator
 
 Sets Decidim::Exporters::CSV's default column separator

data/docs/modules/customize/pages/code.adoc

@@ -1,17 +1,5 @@
 = Code
 
-Decidim is multiple things:
-
-* A command-line utility, which can create an application
-* A set of libraries, that the application can use
-
-Most of the time, you should work with the generated application. That application (development_app on this docs) should be named as your project, for instance for Barcelona City Council is `DecidimBarcelona`, so for creating it should be:
-
-[source,console]
-----
-decidim DecidimBarcelona
-----
-
 If you want to override/change anything, you can just do it with the same name of the file, through Monkey Patching. Some real world examples of this method:
 
 * https://github.com/gencat/participa/blob/master/app/decorators/decidim/admin/selective_newsletter_form_decorator.rb[Decidim::Admin::SelectiveNewsletterForm]. As it's a decorator you also need to make it available in the https://github.com/gencat/participa/blob/3416992ae095f6ab1e826fee961253514c4ff0ef/config/application.rb#L48[application config]

data/docs/modules/customize/pages/cookies.adoc

@@ -0,0 +1,109 @@
+= Cookies
+
+With cookie consent we can explain better what cookies do we use, why we're using these cookies, and let the user choose which cookies they want to use.
+
+== Different cookie categories available in Decidim
+
+By default there are four (4) cookie categories: **essential**, **preferences**, **analytics** and **marketing**. To display embedded iframes properly user has to give consent to all categories.
+
+== Adding scripts which require cookie consent
+
+The recommended place for scripts is ```app/views/layouts/decidim/_head_extra.html.erb```.
+For example, if you want to add a script that requires marketing consent, you can add the following code:
+
+[source,javascript]
+----
+<script type="text/plain" data-consent="marketing">
+  console.log('marketing cookies accepted');
+</script>
+----
+
+NOTE: Script type should be "text/plain". Without that, user's cookie consent setting doesn't affect.
+
+== Adding cookie category and cookie documentation
+
+You are able to modify cookie categories via the `consent_gategories` configuration option.
+
+For example if you want to add a "statistics" category you need to add following code to your app's initializer:
+
+[source,ruby]
+----
+Decidim.configure do |config|
+  config.consent_categories = [
+    {
+      slug: "essential",
+      mandatory: true,
+      cookies: [
+        {
+          type: "cookie",
+          name: "_session_id"
+        },
+        {
+          type: "cookie",
+          name: Decidim.consent_cookie_name
+        }
+      ]
+    },
+    {
+      slug: "preferences",
+      mandatory: false
+    },
+    {
+      slug: "analytics",
+      mandatory: false
+    },
+    {
+      slug: "marketing",
+      mandatory: false
+    },
+    {
+      slug: "statistics",
+      mandatory: false,
+      cookies: [
+        type: "cookie",
+        name: "statistics-cookie"
+      ]
+    }
+  ]
+end
+----
+
+When adding cookie categories and cookies also remember to add the following xref:admin:texts.adoc[translations]:
+
+For category:
+
+[listing]
+----
+layouts.decidim.cookie_consent.modal.statistics.title
+layouts.decidim.cookie_consent.modal.statistics.description
+----
+
+For cookie:
+
+[listing]
+----
+layouts.decidim.cookie_consent.cookie_details.cookies.statistics-cookie.description
+layouts.decidim.cookie_consent.cookie_details.cookies.statistics-cookie.service
+----
+
+* Description explains the purpose of using this cookie
+* Service explains the 3rd party service where this cookie is coming from
+
+So, for instance for the English language (`en`), it would look like this:
+
+[source,yaml]
+----
+en:
+  layouts:
+    decidim:
+      cookie_consent:
+        modal:
+          statistics:
+            title: The title for the statistics
+            description: The description for the statistics
+        cookie_details:
+          cookies:
+            statistics-cookie:
+              description: The purpose of the cookie
+              service: The 3rd party service of the cookie
+----

data/docs/modules/customize/pages/index.adoc

@@ -0,0 +1,28 @@
+= Customize
+
+Decidim is multiple things:
+
+* A command-line utility, which can create an application
+* A set of libraries, that the application can use
+
+Most of the time, you should work with the generated application. That application (development_app on this docs) should be named as your project, for instance for Barcelona City Council is `DecidimBarcelona`, so for creating it should be:
+
+[source,console]
+----
+decidim DecidimBarcelona
+----
+
+Inside of your application you can customize it in different ways:
+
+* xref:customize:authorizations.adoc[Authorizations]
+* xref:customize:code.adoc[Code]
+* xref:customize:gemfile.adoc[Gemfile]
+* xref:customize:images.adoc[Images]
+* xref:customize:javascript.adoc[Javascript]
+* xref:customize:menu.adoc[Menu]
+* xref:customize:oauth.adoc[OAuth]
+* xref:customize:styles.adoc[Styles]
+* xref:customize:texts.adoc[Texts]
+* xref:customize:users_registration_mode.adoc[User registration mode]
+* xref:customize:views.adoc[Views]
+

data/docs/modules/customize/pages/logic.adoc

@@ -0,0 +1,103 @@
+= Change Decidim core logic within your application
+
+There are occasions you find yourself in a situation that you need to change Decidim core logic within your application. There are two ways to accomplish this goal, and we are going through these options here.
+As an example, we will add a new validation rule to the Admin panel, where Admin can not add projects with budgets more than half the total budget. Once we applied such limitation, admins should not be able to add a project with the cost of 5,001 euros to a budget with total of 10,000 euros.
+
+[#maximum-budget-rule]
+.Trying to create a project with the budget of €5,001 for a budget with the total amount of €10,000(My budget) reults in error(buttom-right error message)
+
+image::maximum_budget.png[Maximum budget error]
+
+==  1. Direct change from your application
+
+This method is more straight-forward, and easier to learn. To change the logic in Decidim, identify which part of the source code you need to change. The best way to achieve this is to identify the module being responsible for handling the functionality you want to change. Next, copy the file you want to change from the Decidim gems to your application and use exactly the same directory structure as the destination as in the original gem. Finally, change the code as you wish and make sure that the changes are being applied by testing it in your browser.
+To achieve the change we want to accomplish, we need to go through the following steps:
+
+. Investigate the original source code, where the validation for new projects are defined; in this case, it is decidim-budgets/app/form/decidim/budgets/admin/project_form.rb(refer to xref:#explanation[Extra notes] for more information).
+. Create the same directory path inside your application `mkdir -p app/forms/decidim/budgets/admin` as for the original file.
+. Copy the file from `decidim-budgets` to the newly created directory `cp $(bundle show decidim-budgets)/app/forms/decidim/budgets/admin/project_form.rb app/forms/decidim/budgets/admin/`.
+. Implement the change in the copied file, in this case add the following validation as explained below.
+. In the copied file, add/edit a validation for maximum allowable value:
+[source,ruby]
+----
+  #...
+  validates :budget_amount, numericality: { less_than_or_equal_to: :maximum_budget }
+  #...
+  private
+    #...
+    def maximum_budget
+      (budget[:total_budget] * 0.5).round
+    end
+----
+[start=6]
+. Save the file and restart the server from the console (just to be sure), and check if the changes has taken effect by trying to submit the form.
+. Try to create a project with the budget of €5,001 for a budget with the total amount of €10,000 (e.g. "My budget").
+. You should see an error under the project budget field after submitting the form if everything went as expected.
+
+[#maximum-budget-error]
+.Error messages indicating the exceeding the maximum budget rule.
+
+image::error_max_budget.png[Error for reaching maximum budget]
+NOTE: Remember to add tests for your coded wherever it is needed.
+
+== 2. Override logic with a concern
+
+Concerns allow us to add functionality into existing classes so that the including class can use the added functionality. This is a pattern provided by the Rails framework and you can learn more about it from the https://api.rubyonrails.org/classes/ActiveSupport/Concern.html[Rails API documentation]
+Simply put, a concern allows developers to change only the parts of the original code that need to be changed. This might be a block of a code we need to change, or add/edit an existing method, etc.
+
+The benefit of using concerns is that when we update Decidim gems to new versions, we do not have to necessarily go through all our customizations and we can just focus on those parts that we really want to change. This is slightly harder to do than the first example but in the long run it will pay you back as you will save a lot of time when updating Decidim.
+
+Concerns should be placed into the `concerns` folder within the top-level folder where you want to apply these concerns. In this case, we are adding a concern for the forms classes, so we should place the concerns related to forms to `app/forms/concerns`. If you do not have this folder available, create it first `mkdir -p app/forms/concerns`.
+
+Now, let's move our modifications from the first copy-paste example into a concern.
+
+. Create the file `app/forms/concerns/admin_project_form_extensions.rb`, and make the desired changes in that file as follows:
+[source,ruby]
+----
+# frozen_string_literal: true
+module AdminProjectFormExtensions
+  extend ActiveSupport::Concern
+    included do
+      validates :budget_amount, numericality: { less_than_or_equal_to: :maximum_budget }
+    end
+  private
+    def maximum_budget
+      (budget[:total_budget] * 0.5).round
+    end
+end
+----
+[start=2]
+. After the concern is created, we need to apply it to the correct class. We can do this in the `to_prepare` hook in `config/application.rb`:
+[source,ruby]
+----
+  config.to_prepare do
+    Decidim::Budgets::Admin::ProjectForm.include(Decidim::Budgets::Admin::ProjectForm.include(AdminProjectFormExtensions)
+  end
+----
+This applies to almost all classes you want to change in Decidim but controllers and helpers are special cases due to order of how things are loaded in the Decidim boot process. If you want to add any changes to controllers or helpers, you need to wrap the `config.to_prepare` block within an initializer that is run at the correct phase of the boot process as follows:
+[source,ruby]
+----
+  initializer "customizations", after: "decidim.action_controller" do
+    config.to_prepare do
+      # Add the controller/helper customizations here
+    end
+  end
+----
+[start=3]
+. Restart the server to apply these changes, as we changed the configuration of the application.
+
+[#explanation]
+== Extra notes
+
+The following step would help you find original source code:
+
+* Because we are changing something in the budgets component, we expect to find this file from the decidim-budgets module
+* To find where the gem is located, run the following command within your application:
+
+[source,ruby]
+----
+  bundle show decidim-budgets
+----
+
+* Look at the URL in the view which you want to change. This should generally provide you a hint where to find the correct file to change if you are already familiar with the Rails framework to begin with.
+* As we are changing a validation rule, we expect these kinds of rules to be defined in the form objects which control the different forms in Decidim (so look into the app/forms folder within decidim-budgets).

data/docs/modules/customize/pages/styles.adoc

@@ -56,8 +56,8 @@ Decidim uses Webpacker to compile assets. There are two ways to customize CSS:
 
 1. if you want to redefine just CSS vars or Foundation settings, use _decidim-settings.scss
 2. if you want to redefine a specific snippet of CSS (let's say a few classes but not a whole file) you can use decidim_application.scss
-3. and of course you can overwrite whole files by copying them into the application i.e: to replace `decidim-core/app/packs/stylesheets/modules/_cookie-bar.scss` you should create in your Rails app a file in
-  `app/packs/stylesheets/modules/_cookie-bar.scss` and it will have more priority over the Decidim file.
+3. and of course you can overwrite whole files by copying them into the application i.e: to replace `decidim-core/app/packs/stylesheets/decidim/modules/_cookie-consent.scss` you should create in your Rails app a file in
+  `app/packs/stylesheets/decidim/modules/_cookie-consent.scss` and it will have more priority over the Decidim file.
 
 We use http://sass-lang.com/guide[SASS, with SCSS syntax] as CSS preprocessor.
 

data/docs/modules/develop/pages/api.adoc

@@ -4,12 +4,8 @@ Decidim comes with a powerful API in read-only mode based in the GraphQL specifi
 
 Documentation for this API is auto-generated in each instance of Decidim, usually under the URL:
 
-`some_domain/api/docs`
+`https://example.org/api/docs`
 
-Accessing that URL will give a full details of all the objects that can be requested and how.
+Accessing that URL will give a full details of all the objects that can be requested and how. It includes the full field types reference.
 
-For a quick introduction about how to use the Decidim API, please refer to this document:
-
-xref:../../decidim-api/docs/usage.adoc[Using the Decidim GraphQL API]
-
-Note that this document is available under the `api/docs` URL nicely formatted as well. It also includes the full field types reference.
+As an alternative, if you can't access that URL on your instance you can read about how this work https://github.com/decidim/decidim/blob/develop/decidim-api/docs/usage.md[Using the Decidim GraphQL API].

data/docs/modules/develop/pages/guide_development_app.adoc

@@ -8,14 +8,15 @@ system and services requirements, like having a working Ruby installation, Postg
 
 You'll need to configure the PostgreSQL database before anything. For this,
 
-1. Configure postgresql with a super-user. For instance, for a user called `decidim_development_app_user` with password `changeme`, it'd be:
+. Configure postgresql with a super-user. For instance, for a user called `decidim_development_app_user` with password `changeme`, it'd be:
 
 [source,console]
 ----
 sudo -u postgres psql -c "CREATE USER decidim_development_app_user WITH SUPERUSER CREATEDB NOCREATEROLE PASSWORD 'changeme'"
 ----
 
-2. Save the database configuration in your environment variables configuration. If you've followed the xref:install:manual.adoc[Decidim installation manual],
+[start=2]
+. Save the database configuration in your environment variables configuration. If you've followed the xref:install:manual.adoc[Decidim installation manual],
 then you should have a working https://github.com/rbenv/rbenv-vars[rbenv-vars] in your environment:
 
 [source,console]
@@ -26,7 +27,8 @@ echo "DATABASE_PASSWORD=changeme" >> ~/.rbenv-vars
 
 Of course you should change the password before anything.
 
-2. Then you can create a `development_app` from inside the project's root folder with the command:
+[start=3]
+. Then you can create a `development_app` from inside the project's root folder with the command:
 
 [source,console]
 ----

data/docs/modules/develop/pages/guide_migrate_webpacker_app.adoc

@@ -68,8 +68,8 @@ You can download these files directly with these commands:
 
 [source,console]
 ----
-mkdir -p app/packs/src/decidim app/packs/stylesheets/decidim app/packs/stylesheets/images
-touch app/packs/src/decidim/.keep app/packs/stylesheets/decidim/.keep app/packs/stylesheets/images/.keep
+mkdir -p app/packs/src/decidim app/packs/stylesheets/decidim app/packs/images
+touch app/packs/src/decidim/.keep app/packs/stylesheets/decidim/.keep app/packs/images/.keep
 wget https://raw.githubusercontent.com/decidim/decidim/develop/decidim-generators/lib/decidim/generators/app_templates/decidim_application.js -O app/packs/src/decidim/decidim_application.js
 wget https://raw.githubusercontent.com/decidim/decidim/develop/decidim-generators/lib/decidim/generators/app_templates/decidim_application.scss -O app/packs/stylesheets/decidim/decidim_application.scss
 wget https://raw.githubusercontent.com/decidim/decidim/develop/decidim-generators/lib/decidim/generators/app_templates/_decidim-settings.scss -O app/packs/stylesheets/decidim/_decidim-settings.scss
@@ -84,6 +84,16 @@ Copy the existing images from `app/assets/images` to `app/packs/images`. Images
 cp -rp app/assets/images/* app/packs/images/
 ----
 
+For instance, add the image "app/packs/images/test.png" in a view using the helper:
+
+[source,erb]
+----
+<%= image_pack_tag "media/images/test.png" %>
+----
+
+Note that, by default, all images are flattened in a single directory (any subdirectory structure is lost when requiring an image using the `image_pack_tag`).
+So, if you have a file in a subdirectory such as `app/packs/images/subfolder/test.png`, you still need to call for the image using `image_pack_tag "media/images/test.png"`
+
 === Migrate stylesheets
 
 Existing stylesheets should be moved from `app/assets/stylesheets` to `app/packs/stylesheets` and imported with `@import` into `decidim_application.scss`. Take into account that you might need to adjust a bit the paths of the `@import` to adjust them to the new locations.
@@ -111,6 +121,16 @@ Sometimes assets are included in `vendor/assets/` folder or imported from gems.
 1. if the asset is a javascript that is available as npm package the recommendation is to add it to package.json with `npm install`. If it's not available you might want to copy it to `app/packs/src` and import it.
 2. if the asset is a stylesheet it should be copied to `app/packs/stylesheets` and imported with `@import...` from `_decidim-settings.scss`. Alternatively you can use the optional asset includes as described below to include these in the Decidim main SCSS files.
 
+=== Migrate uploads to ActiveStorage
+
+The old method (CarrierWave) to handle user uploads has changed, now it uses ActiveStorage.
+This means that all the old files need to be migrated to the new system. Use the following rake task to perform this task:
+
+[source,console]
+----
+RAILS_ENV=production bin/rails decidim:active_storage_migrations:migrate_from_carrierwave_to_active_storage
+----
+
 === Optional asset includes
 
 Decidim Webpacker provides a new configuration convention that allows you to add extra configurations for webpacker using a configuration file named `config/assets.rb`. Within this file, you have the following API methods available:
@@ -177,7 +197,7 @@ Decidim.register_assets_path File.expand_path("app/packs", Rails.application.roo
 
 The deployment needs to be updated to manually run `npm install` before assets are precompiled.
 
-In the case of Capistrano this can be done with a before hook:
+In the case of Capistrano this can be done with a before hook (can be added at the end of your `config/deploy.rb` file):
 
 [source,ruby]
 ----
@@ -186,9 +206,7 @@ namespace :deploy do
   task :decidim_webpacker_install do
     on roles(:all) do
       within release_path do
-        with rails_env: fetch(:rails_env) do
-          execute "npm ci"
-        end
+        execute :npm, "install"
       end
     end
   end
@@ -199,6 +217,7 @@ end
 
 Also, in the case of Capistrano it's interesting to add to the shared_paths the following folders:
 
+* `storage` *IMPORTANT!*
 * `tmp/webpacker-cache`
 * `node_modules`
 * `public/decidim-packs`
@@ -215,3 +234,24 @@ npm ERR!
 ----
 
 Then you need to check again that you're using the correct Node.js and NPM versions.
+
+In some case it might be that some packages are not well resolved when installing NPM modules. If you get messages like:
+
+[source,console]
+----
+...
+[webpack-cli] Error: Cannot find module '@rails/webpacker'
+...
+----
+
+These might be due some kind of corruption in your `package-json.lock` file, you can try either to remove this file and recreate it with `npm install` or to add the package `@rails/webpacker` manually in your `package.json` file next to the `@decidim/webpacker` package:
+
+[source,json]
+----
+...
+    "@decidim/webpacker": "^0.25.2",
+    "@rails/webpacker": "^6.0.0-rc.5",
+...
+----
+
+Then execute `npm install`.

data/docs/modules/develop/pages/maps.adoc

@@ -1,6 +1,6 @@
 = Custom map providers
 
-Decidim can be configured to use multiple different xref:/docs/services/maps.adoc[map service providers] but it can be also extended to use any possible service provider out there.
+Decidim can be configured to use multiple different xref:services:maps.adoc[map service providers] but it can be also extended to use any possible service provider out there.
 
 If you want to create your own provider integration, you will need to find a service provider that provides all the following services:
 
@@ -12,12 +12,12 @@ on the proposal pages.
 This service is optional as Decidim will use the dynamic map tiles to generate a similar map element if the static map image cannot be provided.
 
 One option is to host some or all of these services yourself as there are open source alternatives available for all of these services.
-More information about self hosting is available at the link:/docs/services/maps.md#combining-multiple-service-providers[maps and geocoding configuration] documentation.
+More information about self hosting is available at the xref:services:maps.adoc#combining-multiple-service-providers[maps and geocoding configuration documentation].
 
-You may also decide to link:/docs/services/maps.md#disabling[disable some of the services] that are not available at your service provider but in order to get the full out of Decidim, it is recommended to find a service provider with all these services.
+You may also decide to xref:services:maps.adoc#disabling[disable some of the services] that are not available at your service provider but in order to get the full out of Decidim, it is recommended to find a service provider with all these services.
 
 In case you want to use different service providers for the different categories of map services, that is also possible.
-Instructions for this are provided in the link:/docs/services/maps.md#combining-multiple-service-providers[maps and geocoding configuration] documentation.
+Instructions for this are provided in the xref:services:maps.adoc#combining-multiple-service-providers[maps and geocoding configuration documentation].
 
 == Creating your own map service provider
 
@@ -312,7 +312,7 @@ For the dynamic map functionality, you should primarily use a service provider t
 You can also integrate to services that are not compatible with Leaflet but it will cause you more work and is not covered by this guide.
 
 Please note that you don't necessarily even need to create your own dynamic maps utility if your service provider is already compatible with the link:/decidim-core/lib/decidim/map/provider/dynamic_map/osm.rb[`Decidim::Map::Provider::DynamicMap::Osm`] provider.
-In order to configure your custom OSM compatible service provider take a look at the link:/docs/services/maps.md#configuring-open-street-maps-based-service-providers[maps and geocoding configuration] documentation.
+In order to configure your custom OSM compatible service provider take a look at the xref:services:maps.adoc#configuring-open-street-maps-based-service-providers[maps and geocoding configuration] documentation.
 
 If your service provider is not fully compatible with the default OSM provider, you can start writing your customizations by creating an empty dynamic map provider utility with the following code:
 
@@ -496,4 +496,4 @@ In this case, the static map utility can be empty as you won't need any customiz
 
 After you have finished all the steps shown above, you will need to configure your service provider for Decidim.
 The configuration key for the example service provider referred to in this documentation would be `:your_provider`.
-For configuration, refer to the xref:/docs/services/maps.adoc[maps and geocoding configuration] documentation.
+For configuration, refer to the xref:services:maps.adoc[maps and geocoding configuration documentation].

data/docs/modules/develop/pages/metrics.adoc

@@ -117,3 +117,7 @@ Relations around `decidim_metrics` table:
                            | [polymorphic]  |
                            +----------------+
 ----
+
+== Troubleshooting
+
+If you find problems in your metrics numbers you can follow the guide xref:develop:troubleshooting_metrics.adoc[Troubleshooting metrics].

data/docs/modules/develop/pages/modules.adoc

@@ -101,7 +101,7 @@ the https://github.com/decidim/decidim/network/dependents[dependency graph]. See
   . Using the Admin panel
   . Generate logs on Admin panel if admins can operate on it
   . GraphQL API
-  . Data Portability
+  . Download your data
   . Endorsable
   . Followable
   . Embeddable

data/docs/modules/develop/pages/newsletter_templates.adoc

@@ -2,7 +2,7 @@
 
 The newsletter templates allow the user to select a template amongst a set of of them, and use it as base to send newsletters. This allow for more customization on newsletter, tematic newsletters, etc.
 
-Code-wise, they use the content blocks system internally, so https://github.com/decidim/decidim/blob/develop/docs/advanced/content_blocks.md[check the docs] for that section first.
+Code-wise, they use the content blocks system internally, so xref:develop:content_blocks.adoc[check the docs] for that section first.
 
 == Adding a new template