--- title: Move reference docs from Asciidocalypse description: This page is divided into three sections: How Reference Content Works in V3 – Useful for contributors who want to understand the difference between PR... url: https://www.elastic.co/elastic/docs-builder/docs/3522/reference/docs-builder/migration/guide/move-ref-docs products: - Elastic Docs Builder --- # Move reference docs from Asciidocalypse This page is divided into three sections: 1. [How Reference Content Works in V3](#how-reference-content-works-in-v3) – Useful for contributors who want to understand the difference between PR previews and full website builds. 2. [How to Move Reference Content](#how-to-move-reference-content) – No longer relevant, as the process has been automated. 3. [How to Manage Moved Reference Content](#how-to-manage-moved-reference-content) – Important for writers responsible for merging reference content. Jump to the relevant section based on your needs. ## How reference content works in V3 There are two use cases for building reference content in V3: - **Preview builds** - **elastic.co/docs builds** Some repositories, like [`elastic/elastic-serverless-forwarder`](https://github.com/elastic/elastic-serverless-forwarder), contain a single chunk of content within the larger `elastic.co/docs` build. This means the structure of the content is the same for both preview builds and the final Elastic.co/docs build. However, most repositories contain content that will live in multiple locations within the new `elastic.co/docs` IA. Consider `apm-agent-android` as an example. It has the following content: - Reference docs - Release notes - Known issues - Breaking changes - Deprecations ### Directory Structure Release notes do **not** require individual `toc.yml` files for each content set. The directory structure for `apm-agent-android` therefore follows this format: ```md docs/ `docset.yml` * Defines substitutions * Includes all `toc.yml` files in this repo * Ignored by the assembler reference/ `toc.yml` (for this directory) All reference `.md` files go here release-notes/ `toc.yml` (for this directory) All release notes, known issues, breaking changes, and deprecations files go here images/ All image files for all content sets ``` ### Preview Site vs. Full Site Structure For individual repository preview builds, **all** content in the `docs/` directory builds together, appearing as: ```md > Reference Page one Page two Page three > Release notes > Known issues APM Android Agent > Breaking changes APM Android Agent > Deprecations APM Android Agent APM Android Agent release notes ``` This structure is defined in the repo's `docset.yml` file. For the **full Elastic.co/docs site**, the assembler references the individual content set definitions (`toc.yml`) within the repo and organizes the content accordingly: ![Diagram of how everything maps together](https://www.elastic.co/elastic/docs-builder/docs/3522/reference/docs-builder/images/great-drawing-of-new-structure.png) ## How to Move Reference Content The moving of reference content has been automated. These docs will live on in the short term as a point of reference. The steps below explain how to move reference content. You can also take a look at our [sample PR](https://github.com/elastic/apm-agent-android/pull/398), which has specific commits to illustrate some of the steps below. ### Step 1: Delete Existing AsciiDoc Files Skip this step for **any Cloud repos** and the **search-ui repository**. Ensure you only delete **external documentation files**. - In some repositories, this means deleting the entire `/docs` directory. - In others, manually verify which files should be removed. - Use [`conf.yaml`](https://github.com/elastic/docs/blob/master/conf.yaml) to determine what should and shouldn't be removed. Example commit: [#398/commit](https://github.com/elastic/apm-agent-android/pull/398/commits/749803ae9bccdb9f8abdf27a5c7434350716b6c0) ### Step 2: Copy and Paste New Content Move content from `asciidocalypse` to the correct directory in the target repo. Use [issue#130](https://github.com/elastic/docs-eng-team/issues/130) to determine the correct path structure. Example commit: [#398/commit](https://github.com/elastic/apm-agent-android/pull/398/commits/3f966b0e1fa2f008da23d02f2c9e91a60c1bdf8d) ### Step 3: Add the new CI checks Add three workflow files from [`elastic/docs-actions`](https://github.com/elastic/docs-actions) (`@v1`). Full copy-paste examples and explanations are in [How to set up docs previews](https://www.elastic.co/elastic/docs-builder/docs/3522/reference/docs-builder/migration/guide/how-to-set-up-docs-previews). **`docs-build.yml`** — `.github/workflows/docs-build.yml` ```yml name: docs-build on: pull_request: types: [opened, synchronize, reopened] push: branches: - main - '\d+.\d+' merge_group: ~ permissions: contents: read pull-requests: read jobs: build: uses: elastic/docs-actions/.github/workflows/docs-build.yml@v1 with: path-pattern: docs/** use-release-branches: true ``` [`docs-build.yml`](/elastic/docs-builder/docs/3522/reference/docs-builder/migration/guide/how-to-set-up-docs-previews#build) **`docs-deploy.yml`** — `.github/workflows/docs-deploy.yml` ```yml name: docs-deploy on: workflow_run: workflows: [docs-build] types: [completed] permissions: contents: read deployments: write id-token: write pull-requests: write actions: read jobs: deploy: uses: elastic/docs-actions/.github/workflows/docs-deploy.yml@v1 with: path-pattern: docs/** use-release-branches: true ``` [`docs-deploy.yml`](/elastic/docs-builder/docs/3522/reference/docs-builder/migration/guide/how-to-set-up-docs-previews#deploy) **`docs-preview-cleanup.yml`** — `.github/workflows/docs-preview-cleanup.yml` ```yml name: docs-preview-cleanup on: pull_request_target: types: - closed jobs: cleanup: uses: elastic/docs-actions/.github/workflows/docs-preview-cleanup.yml@v1 permissions: contents: none id-token: write deployments: write ``` [`docs-preview-cleanup.yml`](/elastic/docs-builder/docs/3522/reference/docs-builder/migration/guide/how-to-set-up-docs-previews#preview-cleanup) If the documentation you are adding will not live in the `/docs/*` dir of the repository, you must update `path-pattern` on **both** `docs-build` and `docs-deploy` (and adjust `use-release-branches` only if your branching strategy requires it). Please reach out in #docs-team if you need help with this. If you only use continuous deployment from `main` (no release-line branches), omit `\d+.\d+` from `push.branches`, remove `use-release-branches`, and drop the matching `with:` from **docs-deploy** — see the minimal examples in [How to set up docs previews](https://www.elastic.co/elastic/docs-builder/docs/3522/reference/docs-builder/migration/guide/how-to-set-up-docs-previews). Example PR: [#398](https://github.com/elastic/apm-agent-android/pull/398) ### Step 4: Delete the asciidoc warning Skip this step for **any Cloud repos** and the **search-ui repository**. During the migration freeze, we added a check to each repository that warned when a PR was opened against asciidoc files in `main`. It is now safe to remove this file. File to delete: `.github/workflows/comment-on-asciidoc-changes.yml` Example commit: [#398/commit](https://github.com/elastic/apm-agent-android/pull/398/commits/be422934e79c5ecadd7b76523d2e1676fc86f323) ### Step 4: Wait for CI to Pass Verify that all automated checks pass before proceeding. If you encounter any linking failures and need help resolving them, reach out in the typical docs channels. ### Step 5: Merge the PR Once everything is confirmed working, merge the pull request. ### Step 6: Update the Tracking Issue Update [issue#130](https://github.com/elastic/docs-eng-team/issues/130) to reflect the completed migration. ## How to manage moved reference content You've been assigned to a repository in [issue #130](https://github.com/elastic/docs-eng-team/issues/130). Now what? The good news: all necessary PRs have already been opened for you. Each repository has two PRs: 1. A PR that adds GitHub Actions for build previews ([example](https://github.com/elastic/ecs-logging/pull/85)). 2. A PR that removes AsciiDoc content and adds Markdown content ([example](https://github.com/elastic/ecs-logging/pull/84)). ### Your Role Ideally, your job is to work with codeowners and repo admins to: 1. **Get the first PR merged** (to ensure previews work). 2. **Merge `main` into the second PR and get it merged**. Splitting this into two PRs ensures that content is merged with a clean CI pass on the first attempt. ### Alternative Approach Some repositories may be more challenging to work with. If needed, you can cherry-pick the commits into a single PR and collaborate with codeowners to get it merged. **Downside:** We won't know if CI passes until after merging. **Use your judgment**—choose the best approach for your situation. ### Key Considerations Before merging, review the following: - **Is the right content being deleted?** Ensure no essential internal docs are being removed. - **Is the correct content being moved?** Double-check that everything is in its proper place. - **Are tests passing?** If not, what adjustments are needed to make the content mergeable? Let us know if you encounter any blockers. Thanks for your help!