{"id":34666912,"url":"https://github.com/dovecot/documentation","last_synced_at":"2026-06-27T22:01:02.451Z","repository":{"id":36959432,"uuid":"227780279","full_name":"dovecot/documentation","owner":"dovecot","description":"doc.dovecot.org source repository","archived":false,"fork":false,"pushed_at":"2026-06-11T12:40:49.000Z","size":8318,"stargazers_count":23,"open_issues_count":25,"forks_count":83,"subscribers_count":13,"default_branch":"main","last_synced_at":"2026-06-11T14:11:51.196Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dovecot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-12-13T07:20:16.000Z","updated_at":"2026-06-11T12:39:19.000Z","dependencies_parsed_at":"2026-04-21T07:01:47.593Z","dependency_job_id":null,"html_url":"https://github.com/dovecot/documentation","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/dovecot/documentation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dovecot%2Fdocumentation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dovecot%2Fdocumentation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dovecot%2Fdocumentation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dovecot%2Fdocumentation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dovecot","download_url":"https://codeload.github.com/dovecot/documentation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dovecot%2Fdocumentation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34869004,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T19:15:15.677Z","updated_at":"2026-06-27T22:01:02.431Z","avatar_url":"https://github.com/dovecot.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dovecot-ce-documentation\n\nStatic website content for Dovecot CE documentation.\n\n## Site Generation Software\n\nThe site is statically generated via the\n[VitePress](https://www.vitepress.dev/) framework.\n\nVitePress is a JavaScript application.  The content pages use markdown, with\nthe ability to layer additional VitePress (and [Vue](https://www.vuejs.org))\nfunctionality on top of it, i.e. the ability to use templates/variables to\ngenerate page content.\n\nMost maintenance tasks on the JavaScript code use simple functionality using\nbasic JavaScript components. The Mozilla reference page might be useful if\nthere are any questions:\nhttps://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference\n\nMarkdown reference: https://www.markdownguide.org/\n\nConfiguration of VitePress is in the `.vitepress/config.js` file.\n\n### Prerequisites\n\nFrom [VitePress](https://vitepress.dev/guide/getting-started#prerequisites):\n\n* Node.js **version 18+**\n  * Alternatively, Bun (https://bun.sh/) can be used instead.\n\n\u003e [!WARNING]\n\u003e Ubuntu 22.04 LTS (and prior) does NOT contain a new enough version of nodejs.\n\u003e\n\u003e Either run in a container (see https://hub.docker.com/_/node) or install\n\u003e via out-of-band packages (see https://github.com/nodesource/distributions).\n\n## Installation\n\n\u003e [!NOTE]\n\u003e Instead of `npm` you can use any compatible node package managing software:\n\u003e `pnpm`, `yarn`, `bun`, etc.\n\nTo install, run:\n\n```sh\nnpm install\n```\n\n## Local Testing Server\n\nVitePress provides a local development server that will do real-time updates\nwhen source files change.\n\n\u003e [!IMPORTANT]\n\u003e This must be run from the base of the project!\n\nRun with:\n\n```sh\nnpm run docs:dev\n```\n\n\u003e [!NOTE]\n\u003e Certain features (such as search) will not work in testing/dev mode and\n\u003e require the documentation to be statically built and served.\n\n## Documentation Generation\n\nTo generate the static documentation, run:\n\n```sh\nnpm run docs:build\n```\n\nGenerated documentation will be output in the `docs/.vitepress/dist` directory.\nThe statically generated documentation can be displayed locally by running:\n\n```sh\nnpm run docs:preview\n```\n\n### Debugging\n\nDepending on when an issue occurs, errors may be displayed on the development\nscreen (and in the terminal where the `docs:dev` command is being run).\n\nHowever, some errors only occur when viewing a page, and will oftentimes\nresult in a blank or incomplete page render. In these cases, looking at the\nbrowser developer console will generally show the error that has occurred.\n\n## Docker Container\n\nAn updated Docker container is produced after every code addition, and can be\nused to view the documentation locally.\n\nContainer installation information can be found at:\nhttps://github.com/dovecot/documentation/pkgs/container/documentation\n\nThe container exposes a web server on port 80, and the documentation is available\nin the `2.4` directory.\n\n### Example\n\nProvide access to Dovecot documentation at `http://localhost:8080/`:\n\n```sh\ndocker run --rm \\\n  -p 8080:80 \\\n  ghcr.io/dovecot/documentation:latest\n```\n\n## Dovecot-specific VitePress Features\n\n### Directory Structure\n\n`docs/` contains the pages to be rendered by VitePress into the site.\n\n### Sidebar Generation\n\nThe sidebar is automatically generated via the\n[vitepress-sidebar](https://github.com/jooy2/vitepress-sidebar) plugin.\n\nIt will create the sidebar based on the file layout in the `docs/` directory.\n\nThe title is configured via the `title` parameter in the\n[frontmatter](https://vitepress.dev/guide/frontmatter) content of the page.\n\nAny page can be excluded from output by setting the `exclude` parameter to\n`true` in the frontmatter content of the page.\n\nHeader titles can be set via the `index.md` file in the folder. This file\ncan be hidden by setting the `exclude` parameter to `true`.\n\n### Dovecot Data Generation\n\nDovecot has several systems (configuration, doveadm, events, etc.) that can\nbe added throughout the code and need a way to collect and handle the\ndocumentation in a single location.\n\nThis is accomplished by maintaining a \"database\" of these elements in a\nspecial data file. These data files can then be processed via simple javascript\nand HTML templating to vastly simplify the output of this common data.\n\nAdditionally, this allows this information to be maintained in a single place\nand shown on multiple pages. For example, it is useful on a plugins page to\nshow all configuration settings related to that plugin, but it is also useful\nto have a page that shows all information on all plugin settings.\n\nThe data files live in the base `/data` directory. Each file attempts to be\nself-documenting, but they are all essentially large JSON objects. Developers\nshould need to know basically no JavaScript to be able to edit the files.\n\n### Dovecot VitePress Configuration\n\nAdditional configuration options required for VitePress static generation are\ndefined using the `dovecot` object in the `themeConfig` VitePress\nconfiguration setting.\n\n#### data_paths\n\nAllows custom mapping of data sources.\n\nIt is used by the VitePress data loaders to determine what data to\nload for export.\n\nKeys are data identifiers, Values are location RELATIVE TO `\u003cbase\u003e/lib`\nDIRECTORY.\n\n#### gitrev\n\nConfigures how the current git revision information is displayed in the\npage footer.\n\n##### align\n\nAlignment of the text. Either `left` or `right`.\n\n##### hash\n\nThe git hash of the branch tip.\n\n#### man_includes\n\nA list of additional paths (other than the `include/` directory of the man\nfolder) where include files can live.\n\n#### man_paths\n\nA listing of paths containing man files.\nPaths are relative to project base.\n\nSupports fast-glob: https://github.com/mrmlnc/fast-glob#pattern-syntax\n\n#### markdown_extend\n\nAn object containing callbacks that enable additional labels to support in\nDovecot-specific markdown processing (i.e. [[xyz,...]]).\n\n##### open\n\nOpening tag function. Returns opening tag.\n\nThe opts argument contains a \"resolveURL\" key that allows access to the\ninternal Dovecot Markdown `resolveURL()` function.\n\nExample: `open: (mode, parts, opts, env) =\u003e { return '' }`\n\n##### body\n\nBody function. Returns body text.\n\nExample: `body: (mode, env) =\u003e { return '' }`\n\n##### close\n\nClose tag function. Returns closing tag.\n\nExample: `close: (mode, env) =\u003e { return '' }`\n\n#### plugin_paths\n\nA listing of paths containing plugin files.\nPaths are relative to project base.\n\nSupports fast-glob: https://github.com/mrmlnc/fast-glob#pattern-syntax\n\n#### url_rewrite\n\nA callback where Markdown generated URLs can be rewritten.\nFunction is called the original URL and returns the (modified) URL.\n\nExample: `url_rewrite: (url) =\u003e { return url + '.foo' }`\n\n#### watch_paths\n\nAn array of file patterns to watch to refresh data loaders in dev mode.\nSee: https://vitepress.dev/guide/data-loading#data-from-local-files\nPaths are relative to project base.\n\nSupports fast-glob: https://github.com/mrmlnc/fast-glob#pattern-syntax\n\n### Dovecot Markdown Extensions\n\nMarkdown has been extended to allow various Dovecot-specific tasks to be\nperformed.\n\nThis Markdown works in both the base pages and in many database fields\n(see documentation in `data/*.data.js` for the fields that support Markdown).\n\n\u003e [!NOTE]\n\u003e All Dovecot extended Markdown commands are wrapped in `[[...]]` syntax.\n\n#### Doveadm Commands\n\n***Syntax: `[[doveadm,command_string(,args)]]` (args is optional)***\n\n`command_string` should NOT include \"doveadm\" - this will automatically be\nadded in the output.\n\nIf args is set, it is appended to the display as doveadm arguments. Example:\n\n```\n# [[doveadm,foo,--bar \u0026lt;baz\u0026gt;]] results in:\n\u003ca href=\"PATH_TO_FOO_COMMAND\"\u003edoveadm foo --bar \u0026lt;baz\u0026gt;\u003c/a\u003e\n```\n\n#### Events\n\n***Syntax: `[[event,event_name]]`***\n\n`event_name` is the name of the Dovecot event to link to.\n\n#### Link\n\n***Syntax: `[[link,tag(,optional_text)]]`***\n\nVitePress does not support inter-documentation linking, by default.\n\nHowever, this wiki-like linking is useful and has been custom implemented\nin Dovecot's implementation of VitePress.\n\nDovecot linking \"tags\" are defined in a page's Frontmatter (the YAML at\nthe top of the page) under the `dovecotlinks` key.\n\n`dovecotlinks` keys are the link tags.  Values are one of two formats:\n\n* If text, this the default text associated with the tag. A link to this tag\n  will link the to base page.\n* If an object, it must define two sub-keys: `hash` and `text`\n  * `hash` is the anchor on the page to link to when using the tag. The '#'\n    MUST not be present. Hash strings can be determined by mousing over\n    headers on a page. (Roughly: every non-character is converted to '-'.)\n  * `text` is the default text for the tag.\n\n#### Man Pages\n\n***Syntax: `[[man,command_name(,hash,section)]]`***\n\nLinks to the man page.\n\n`command_name` is the command to link to (e.g., `doveconf`).\n\nHash is the section number.  It defaults to empty.\n\nSection is the section number.  It defaults to `1`.\n\n#### Plugin\n\n***Syntax: `[[plugin,plugin_name(,text)]]`***\n\nLinks to the plugin page.\n\nIf `text` is set, it is used as the link text instead of the plugin name.\n\n#### RFC\n\n***Syntax: `[[rfc,rfc_number(,section)]]`***\n\nLinks to the RFC page (external).\n\n`section` is optional and will link to the RFC subsection.\n\n#### Settings\n\n***Syntax: `[[setting,setting_name(,args)]]`***\n***Syntax: `[[setting_text,setting_name(,text)]]`***\n\nFor the `setting` variant, if args is set, it is appended to the display as a\nsetting value. Example:\n\n```\n# [[setting,foo,5]] results in:\n\u003ca href=\"PATH_TO_FOO_SETTING\"\u003efoo = 5\u003c/a\u003e\n```\n\nFor the `setting_text` variant, if text is set, it is used as the link text.\nExample:\n\n```\n# [[setting_text,foo,bar]] results in:\n\u003ca href=\"PATH_TO_FOO_SETTING\"\u003ebar\u003c/a\u003e\n```\n\n#### Variable\n\n***Syntax: `[[variable(,section)]]`***\n\nLink to the Settings Variable page.\n\nBy default, links to the base page.\n\nIf section is defined, will link to the sub-section. Valid sub-sections:\n\n* `auth`\n* `settings` (default)\n* `global`\n* `login`\n* `mail-service-user`\n* `mail-user`\n\n#### Updates (added, changed, deprecated, removed)\n\n***Syntax: `[[(update),tag_name]]`***\n\nCreate a update tag based on a tag_name.\n\nThe tag_name must be defined in `data/updates.js`.\n\nExample: `[[changed,tag_name]]`\n\n### Other Markdown Extensions\n\n#### TODO Container\n\n***Syntax:***\n\n```\n::: todo\nTODO text contents\n:::\n```\n\nOutputs a formatted TODO container, using the (optional) TODO text contents\nas the body.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdovecot%2Fdocumentation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdovecot%2Fdocumentation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdovecot%2Fdocumentation/lists"}