# Maintaining the AsciiDoc guides Edit `src/main/asciidoc/how-to`, not the generated site modules or the former wiki tutorials. Each task has one maintained procedure. Link to the Installation, Administration or Developer's Guide when that procedure already exists there. The `how-to/index.adoc` book includes its chapters using `include::./name.adoc[]`. The Maven `documents` list selects guides for preprocessing, Antora conversion and PDF generation. Register navigation and the generated PDF filename separately in `opendj/antora.yml` in the documentation-site repository. Do not hand-edit the generated `modules` tree there: deployment replaces it. Use `xref:../guide/chapter.adoc#anchor[Title]` for cross-guide links and `xref:./chapter.adoc[Title]` for another How-To. Each chapter must define any attributes it uses, because the site renders chapters separately. Use `subs="+attributes"` on a code block only when it intentionally substitutes an AsciiDoc attribute. Keep language expressions such as Java placeholders literal. ## Getting Started and Release Notes `getting-started` contains the introductory concepts and a runnable first-directory exercise. Keep its download pinned to a published release, even when this repository builds a SNAPSHOT. Re-run the exercise when changing its version or commands. `release-notes` contains version-specific summaries and installation/upgrade considerations. Verify release facts against the tagged source and the GitHub release record. Keep `release-history.adoc` as a dated snapshot of the full published GitHub release descriptions, in reverse publication order. Preserve their text, contributor credits and links when converting Markdown to AsciiDoc; use GitHub publication dates in UTC. Refresh the snapshot and its retrieval date when adding a release. Keep links to the original release records, complete comparisons and security advisories. Add a chapter and update the book includes when documenting a new release; do not silently relabel an older release's notes. Use the release Markdown as the text source. Keep Java tokens such as `@Override` and `@param` literal, retain command placeholders such as `--help-`, and escape three-dot commit ranges so Asciidoctor does not replace them with an ellipsis. Turn issue references and commit ranges into links to this repository's issues and comparisons, preserving their displayed text and surrounding punctuation. Honor explicit repository qualifiers, such as `OpenIdentityPlatform/OpenAM#980`, instead of linking them to OpenDJ. Normalize hyphens in CVE identifiers to ASCII `-` so they remain searchable and copyable. Only the explicit `history-X-Y-Z` release anchors are stable. Link to those anchors, rather than generated subsection IDs such as `_whats_changed_2`, which shift when a new release is prepended. The Release Notes book uses Asciidoctor PDF's bundled `default-with-font-fallbacks` theme for supporter emoji. The `release-heart` attribute preserves the original emoji presentation selector in HTML and omits that invisible selector in PDF, where the bundled fonts do not support it. Both books follow the same Maven, Antora and PDF pipeline as How-To. Their site PDF filenames are `Getting_Started.pdf` and `Release_Notes.pdf`. Register their navigation before the Installation Guide. The historical DocBook sources are maintained separately and are not inputs to these new guides. ## Wiki migration inventory Source: [OpenDJ wiki](https://github.com/OpenIdentityPlatform/OpenDJ/wiki), revision `d0a4db8af19b58815710a5eca7ebc6c0d188c9e0`. | Former wiki page | Maintained destination | | --- | --- | | How To Run OpenDJ in Kubernetes | [how-to/kubernetes](https://doc.openidentityplatform.org/opendj/how-to/kubernetes) | | How to Setup OpenDJ with BCFKS FIPS Key Store Type support | [how-to/bcfks](https://doc.openidentityplatform.org/opendj/how-to/bcfks) | | Using a Relational Database as an LDAP Backend | [how-to/jdbc-backend](https://doc.openidentityplatform.org/opendj/how-to/jdbc-backend) | | How to Run OpenDJ based Embedded LDAP in Spring Boot Application | [how-to/embedded-ldap](https://doc.openidentityplatform.org/opendj/how-to/embedded-ldap) | | REST Access to OpenDJ Directory Server | [how-to/rest-access](https://doc.openidentityplatform.org/opendj/how-to/rest-access) | | How to delegate password reset permissions | [how-to/delegate-password-reset](https://doc.openidentityplatform.org/opendj/how-to/delegate-password-reset) | | How to generate test LDIF data and import to LDAP server OpenDJ | [how-to/generate-test-data](https://doc.openidentityplatform.org/opendj/how-to/generate-test-data) | | TIP: How to Persist OpenDJ Docker Container Data Between Restarts | [install-guide/chap-install#install-docker](https://doc.openidentityplatform.org/opendj/install-guide/chap-install#install-docker) | | How To Guides | [how-to/](https://doc.openidentityplatform.org/opendj/how-to/) | | How To | How-To task directory and the recipes below | | Recipe in the former How To collection | Destination | | --- | --- | | Get last version; setup server | Installation Guide: command-line installation | | Clean and reinstall server | Installation Guide: uninstall, then install | | Check server status | Administration Guide: monitoring | | Backup and restore | Administration Guide: backup and restore | | Initialize replication; disable replication | Administration Guide: replication | | List indexes; rebuild degraded indexes | Administration Guide: indexing | | List TLS protocols/ciphers; restrict TLS | Administration Guide: TLS protocols and cipher suites | | Use a certificate with Docker | Connection handlers: certificate preparation; Docker image README: OPENDJ_SSL_OPTIONS | | Cassandra backend | how-to/cassandra-backend.adoc | | JDBC backend | how-to/jdbc-backend.adoc | | Debug instance | how-to/debug-instance.adoc | | Jira integration | Existing link to Atlassian's instructions, retained in how-to/tasks.adoc | The wiki migration from [#1268](https://github.com/OpenIdentityPlatform/OpenDJ/pull/1268) was applied in [wiki commit `80e637c`](https://github.com/OpenIdentityPlatform/OpenDJ/wiki/_history/80e637cc8b073857e2c8be1d31e830c139edf6d4). The former tutorials now contain relocation notices, and the How To collection links to the maintained procedures. Keep the existing wiki filenames so incoming URLs remain useful. The wiki history retains the original text. Do not maintain or synchronize a second full copy of the articles.