Skip to content

# ejabberd Docs Source Code

The ejabberd Community Server has its source code available in the ejabberd git repository. Its documentation is published in the ejabberd Docs website, and its source code is available in the docs git repository.

This is a community effort and you are welcome to submit issues or pull requests in order to improve the docs and benefit the ejabberd community.

This documentation site is built using MkDocs and Material for MkDocs.

## Installation

To build the site you need Python 3.6 or later, then install the dependencies:

### pip

    mkdir -p .venv
    python3 -m venv .venv
    source .venv/bin/activate
    pip install -r requirements.txt

Info

From now on, remember to run `source .venv/bin/activate` before running any `mkdocs [...]` command.

Tip

You can freeze the dependencies to a file using `pip freeze > requirements.txt`.

### Debian

You could install most dependencies using APT:

    apt-get install mkdocs \
                    mkdocs-material \
                    mkdocs-material-extensions \
                    mkdocs-redirects \
                    python3-bs4

Warning

Unfortunately Debian doesn't package `mkdocs-with-pdf`, so you should remove `with-pdf` plugin from `mkdocs.yml`.

## Building

Now you can start a small webserver that builds the site dynamically:

    mkdocs serve

or build the site into static html files in the `site/` directory:

    mkdocs build

## Testing

To verify the internal URLs in the site:

    TEST=true mkdocs serve

To verify the internal URLs and also the external links:

    TEST=true TEST_EXTERNAL=true mkdocs serve

## Updating content

Some pages in this documentation are extracted from a running ejabberd node:

- admin/configuration/toplevel.md
- admin/configuration/modules.md
- developer/ejabberd-api/admin-api.md
- developer/ejabberd-api/admin-tags.md

To update those pages, install ejabberd, start it and run `make all` in this repository. This gets documentation from ejabberd, processes it to obtain markdown content and moves the files to this repository.

Additionally, there are several other pages that are markdown files copied from ejabberd git repository and docker-ejabberd git repository. Those repositories must be available next to docs.ejabberd.im before running `make all`.

## Markdown Shorthands

When editing ejabberd source code to document top-level options, modules or API commands, there is some additional syntax supported to generate HTML URLs:

For example, this text in the ejabberd source code:

    _`mod_muc_admin`_
    _`bookmarks_to_pep`_ API
    _`default_db`_
    _`basic.md#captcha|CAPTCHA`_
    https://xmpp.org/extensions/xep-0045.html[XEP-0045]
    (def:c2s)

gets converted into this markdown:

    [mod_muc_admin](../../admin/configuration/modules.md#mod_muc_admin)
    [bookmarks_to_pep](../../developer/ejabberd-api/admin-api.md#bookmarks_to_pep) API
    [default_db](toplevel.md#default_db)
    [CAPTCHA](basic.md#captcha)
    [XEP-0045](https://xmpp.org/extensions/xep-0045.html)
    [](def:c2s)

There are example usage of those shorthands in ejabberd, for example in `mod_muc.erl`.

## Glossary

### Directly in markdown file

To define a new term, write in markdown:

    def:c2s
    : Client to Server connection in XMPP.

To link to that term, write in markdown:

    Most connections in XMPP are [](def:c2s).

Glossary terms can be defined as singular nouns (`connection`, `port`), and later you can link to that term in plural noun (`connections`, `ports`).

### In ejabberd source code

Term definition is done as expected; example usage:

    mod_doc() ->
        #{desc =>
              [?T("def:ad-hoc command"), "",
               ?T(": Command that can be executed by an XMPP client using XEP-0050."), "",
               ?T("This module implements XEP-0050.")]

In order to link to a term definition, please write simply `(def:c2s)` because `[]` becomes escaped and wouldn't work. Later `make extract` will add the `[]` automatically. Example usage:

    mod_doc() ->
        #{desc =>
              ?T("This module implements some (def:ad-hoc commands) for adminitration.")