= Decidim Developer Documentation

== What is this?

This is the internal Decidim documentation.
If you want to see it in a nice UI you can do it at the https://docs.decidim.org[Decidim Documentation Site].
Some of the sections are available on https://github.com/decidim/documentation[Decidim Documentation repository].

== How this works?

This is made with https://antora.org/[Antora].
It uses https://asciidoc.org/[AsciiDoc] mark-up document format.
It is pretty similar to Markdown, although is more standarized and can do more complex things.
Read more about https://asciidoctor.org/docs/asciidoc-vs-markdown/[Markdown vs AsciiDoc].

If you want to convert from Markdown to AsciiDoc:

. online pandoc conversor or
. using kramdoc:

[source,bash]
----
gem install kramdown-asciidoc
kramdoc --format=GFM --output=your-doc.adoc --wrap=ventilate your-doc.md
----

The nice thing about Antora is that you can have multi-repositories for your documentation, so we have some technical sections in this repository (like Install, Customize and Develop) and other sections that are not for developers or system administrators on the https://github.com/decidim/documentation[other repository].

== Local development

If you want to try changes in this folder and how it'd be shown in https://docs.decidim.org[Decidim Documentation site], you need to do these next steps:

. Clone the repository
. Install dependencies
. Change the antora-playbook.yml url key in source
. Build the antora playbook
. Open the generated website with your web browser

For instructions on how to clone the repository, install dependencies, build the antora playbook and open the generated webiste, see https://github.com/decidim/documentation[Decidim's documentation repository README file].

Regarding "3. Change the antora-playbook.yml url key in source", if this is the configuration at antora-playbook.yml:

[source,yaml]
----
   - url: https://github.com/decidim/decidim
     start_path: docs
     branches: develop
----

Then the result would be:

[source,yaml]
----
   - url: /home/youruser/Work/decidim/decidim
     start_path: docs
     branches: develop
----

If building locally does not show any change, then check also that the branch corresponds with the one that you are working locally.

== Add a new link in the sidebar

For adding a new link in the sidebar you need to add it in https://raw.githubusercontent.com/decidim/documentation/master/en/modules/ROOT/nav.adoc[nav.adoc file]