From 79aff657213f185786d4accf403032887d5a5d26 Mon Sep 17 00:00:00 2001 From: bmorelli25 Date: Tue, 4 Feb 2025 09:51:27 -0800 Subject: [PATCH 1/4] various internal docs improvements --- docs/docset.yml | 6 +- docs/migration/engineering.md | 2 +- docs/migration/guide/automated.md | 257 +++++++++++++++++- docs/migration/guide/bug-bash.md | 58 ---- docs/migration/guide/file-structure.md | 52 ---- docs/migration/guide/index.md | 12 +- docs/migration/guide/mapping.md | 130 +-------- docs/migration/guide/tooling.md | 64 ++++- .../guide/working-in-docs-content.md | 91 +++++++ docs/migration/index.md | 16 +- docs/migration/versioning.md | 2 +- docs/syntax/admonitions.md | 61 ++--- docs/syntax/applies.md | 2 +- docs/syntax/code.md | 65 ++--- docs/syntax/comments.md | 8 +- docs/syntax/conditionals.md | 2 +- docs/syntax/dropdowns.md | 22 -- docs/syntax/example_blocks.md | 2 +- docs/syntax/frontmatter.md | 6 +- docs/syntax/index.md | 69 ++++- docs/syntax/md-extensions.md | 73 ----- docs/syntax/passthrough.md | 2 +- docs/syntax/sidebars.md | 2 +- docs/syntax/sundries.md | 21 +- docs/syntax/tabs.md | 50 ---- docs/syntax/tagged_regions.md | 2 +- 26 files changed, 558 insertions(+), 519 deletions(-) delete mode 100644 docs/migration/guide/bug-bash.md create mode 100644 docs/migration/guide/working-in-docs-content.md delete mode 100644 docs/syntax/md-extensions.md diff --git a/docs/docset.yml b/docs/docset.yml index dcf4a1dc5..ef044b426 100644 --- a/docs/docset.yml +++ b/docs/docset.yml @@ -44,10 +44,9 @@ toc: - folder: guide children: - file: index.md + - file: working-in-docs-content.md - file: automated.md - file: tooling.md - - file: bug-bash.md - - file: file-structure.md - file: mapping.md - folder: configure children: @@ -68,8 +67,8 @@ toc: - folder: syntax children: - file: index.md - - file: md-extensions.md - file: admonitions.md + - file: applies.md - file: automated_settings.md - file: code.md - file: comments.md @@ -82,7 +81,6 @@ toc: - file: line_breaks.md - file: links.md - file: passthrough.md - - file: applies.md - file: sidebars.md - file: substitutions.md - file: sundries.md diff --git a/docs/migration/engineering.md b/docs/migration/engineering.md index f4a1296ae..eff5801fa 100644 --- a/docs/migration/engineering.md +++ b/docs/migration/engineering.md @@ -1,4 +1,4 @@ -# Reference docs guidelines +# New reference guidelines ## Engineering ownership of reference documentation diff --git a/docs/migration/guide/automated.md b/docs/migration/guide/automated.md index be233f3b1..7cf1ce2a5 100644 --- a/docs/migration/guide/automated.md +++ b/docs/migration/guide/automated.md @@ -1,4 +1,4 @@ -# Migrate Automated Content to V3 +# Migrate automated docs If you have automated documentation in Asciidoc (or any other format) that you need to migrate to Elastic docs V3, this guide walks you through the essentials. Elastic docs V3 (powered by `docs-builder`) allows engineering teams to keep code and reference docs closely integrated for easier updates and greater accuracy. @@ -43,4 +43,257 @@ For more information, see [Navigation](../../configure/content-set/navigation.md ## Next steps -That’s all you need to get started migrating automated docs to V3. As you add more pages or custom features, refer to the linked resources for details on configuring your docset, refining navigation, and leveraging the full power of V3 directives. \ No newline at end of file +That’s all you need to get started migrating automated docs to V3. As you add more pages or custom features, refer to the linked resources for details on configuring your docset, refining navigation, and leveraging the full power of V3 directives. + +# Troubleshoot {{elastic-defend}} [ts-management] + + +This topic covers common troubleshooting issues when using {{elastic-defend}}'s [endpoint management tools](../../../solutions/security/manage-elastic-defend.md). + + +## Endpoints [ts-endpoints] + +:::::{dropdown} Unhealthy {{agent}} status +:name: ts-unhealthy-agent + +In some cases, an `Unhealthy` {{agent}} status may be caused by a failure in the {{elastic-defend}} integration policy. In this situation, the integration and any failing features are flagged on the agent details page in {{fleet}}. Expand each section and subsection to display individual responses from the agent. + +::::{tip} +Integration policy response information is also available from the **Endpoints** page in the {{security-app}} (**Manage** → **Endpoints**, then click the link in the **Policy status** column). +:::: + + +:::{image} ../../../images/security-unhealthy-agent-fleet.png +:alt: Agent details page in {{fleet}} with Unhealthy status and integration failures +:class: screenshot +::: + +Common causes of failure in the {{elastic-defend}} integration policy include missing prerequisites or unexpected system configuration. Consult the following topics to resolve a specific error: + +* [Approve the system extension for {{elastic-endpoint}}](../../../solutions/security/configure-elastic-defend/enable-access-for-macos-monterey.md#system-extension-endpoint) (macOS) +* [Enable Full Disk Access for {{elastic-endpoint}}](../../../solutions/security/configure-elastic-defend/enable-access-for-macos-monterey.md#enable-fda-endpoint) (macOS) +* [Resolve a potential system deadlock](../../../troubleshoot/security/elastic-defend.md#linux-deadlock) (Linux) + +::::{tip} +If the {{elastic-defend}} integration policy is not the cause of the `Unhealthy` agent status, refer to [{{fleet}} troubleshooting](../../../troubleshoot/ingest/fleet/common-problems.md) for help with the {{agent}}. +:::: + + +::::: + + +:::::{dropdown} Disabled to avoid potential system deadlock (Linux) +:name: linux-deadlock + +If you have an `Unhealthy` {{agent}} status with the message `Disabled due to potential system deadlock`, that means malware protection was disabled on the {{elastic-defend}} integration policy due to errors while monitoring a Linux host. + +You can resolve the issue by configuring the policy’s [advanced settings](../../../solutions/security/configure-elastic-defend/configure-linux-file-system-monitoring.md) related to **fanotify**, a Linux feature that monitors file system events. By default, {{elastic-defend}} works with fanotify to monitor specific file system types that Elastic has tested for compatibility, and ignores other unknown file system types. + +If your network includes nonstandard, proprietary, or otherwise unrecognized Linux file systems that cause errors while being monitored, you can configure {{elastic-defend}} to ignore those file systems. This allows {{elastic-defend}} to resume monitoring and protecting the hosts on the integration policy. + +::::{warning} +Ignoring file systems can create gaps in your security coverage. Use additional security layers for any file systems ignored by {{elastic-defend}}. +:::: + + +To resolve the potential system deadlock error: + +1. Go to **Manage** → **Policies**, then click a policy’s name. +2. Scroll to the bottom of the policy and click **Show advanced settings**. +3. In the setting `linux.advanced.fanotify.ignored_filesystems`, enter a comma-separated list of file system names to ignore, as they appear in `/proc/filesystems` (for example: `ext4,tmpfs`). Refer to [Find file system names](../../../solutions/security/configure-elastic-defend/configure-linux-file-system-monitoring.md#find-file-system-names) for more on determining the file system names. +4. Click **Save**. + + Once you save the policy, malware protection is re-enabled. + + +::::: + + +:::::{dropdown} Required transform failed +:name: ts-transform-failed + +If you encounter a `“Required transform failed”` notice on the Endpoints page, you can usually resolve the issue by restarting the transform. Refer to [Transforming data](../../../explore-analyze/transforms.md) for more information about transforms. + +:::{image} ../../../images/security-endpoints-transform-failed.png +:alt: Endpoints page with Required transform failed notice +:class: screenshot +::: + +To restart a transform that’s not running: + +1. Go to **Kibana** → **Stack Management** → **Data** → **Transforms**. +2. Enter `endpoint.metadata` in the search box to find the transforms for {{elastic-defend}}. +3. Click the **Actions** menu (**…​**) and do one of the following for each transform, depending on the value in the **Status** column: + + * `stopped`: Select **Start** to restart the transform. + * `failed`: Select **Stop** to first stop the transform, and then select **Start** to restart it. + + :::{image} ../../../images/security-transforms-start.png + :alt: Transforms page with Start option selected + :class: screenshot + ::: + +4. On the confirmation message that displays, click **Start** to restart the transform. +5. The transform’s status changes to `started`. If it doesn’t change, refresh the page. + +::::: + + +:::::{dropdown} {agent} and Endpoint connection issues +:name: ts-agent-connection + +After {{agent}} installs Endpoint, Endpoint connects to {{agent}} over a local relay connection to report its health status and receive policy updates and response action requests. If that connection cannot be established, the {{elastic-defend}} integration will cause {{agent}} to be in an `Unhealthy` status, and Endpoint won’t operate properly. + + +### Identify if the issue is happening [_identify_if_the_issue_is_happening] + +You can identify if this issue is happening in the following ways: + +* Run {{agent}}'s status command: + + * `sudo /opt/Elastic/Agent/elastic-agent status` (Linux) + * `sudo /Library/Elastic/Agent/elastic-agent status` (macOS) + * `c:\Program Files\Elastic\Agent\elastic-agent.exe status` (Windows) + + If the status result for `endpoint-security` says that Endpoint has missed check-ins or `localhost:6788` cannot be bound to, it might indicate this problem is occurring. + +* If the problem starts happening right after installing Endpoint, check the value of `fleet.agent.id` in the following file: + + * `/opt/Elastic/Endpoint/elastic-endpoint.yaml` (Linux) + * `/Library/Elastic/Endpoint/elastic-endpoint.yaml` (macOS) + * `c:\Program Files\Elastic\Endpoint\elastic-endpoint.yaml` (Windows) + + * If the value of `fleet.agent.id` is `00000000-0000-0000-0000-000000000000`, this indicates this problem is occurring. + + ::::{note} + If this problem starts happening after Endpoint has already been installed and working properly, then this value will have changed even though the problem is happening. + :::: + +### Examine Endpoint logs [_examine_endpoint_logs] + +If you’ve confirmed that the issue is happening, you can look at Endpoint log messages to identify the cause: + +* `Failed to find connection to validate. Is Agent listening on 127.0.0.1:6788?` or `Failed to validate connection. Is Agent running as root/admin?` means that Endpoint is not able to create an initial connection to {{agent}} over port `6788`. +* `Unable to make GRPC connection in deadline(60s). Fetching connection info again` means that Endpoint’s original connection to {{agent}} over port `6788` worked, but the connection over port `6789` is failing. + + +### Resolve the issue [_resolve_the_issue] + +To debug and resolve the issue, follow these steps: + +1. Since 8.7.0, Endpoint diagnostics contain a file named `analysis.txt` that contains information about what may cause this issue. As of 8.11.2, {{agent}} diagnostics automatically include Endpoint diagnostics. For previous versions, you can gather Endpoint diagnostics by running: + + * `sudo /opt/Elastic/Endpoint/elastic-endpoint diagnostics` (Linux) + * `sudo /Library/Elastic/Endpoint/elastic-endpoint diagnostics` (macOS) + * `c:\Program Files\Elastic\Endpoint\elastic-endpoint.exe diagnostics` (Windows) + +2. Make sure nothing else on your device is listening on ports `6788` or `6789` by running: + + * `sudo netstat -anp --tcp` (Linux) + * `sudo netstat -an -f inet` (macOS) + * `netstat -an` (Windows) + +3. Make sure `localhost` can be resolved to `127.0.0.1` by running: + + * `ping -4 -c 1 localhost` (Linux) + * `ping -c 1 localhost` (macOS) + * `ping -4 localhost` (Windows) + + +::::: + + +::::{dropdown} {elastic-defend} deployment issues +:name: defend-deployment + +After deploying {{elastic-defend}}, you might encounter warnings or errors in the endpoint’s **Policy status** in {{fleet}} if your mobile device management (MDM) is misconfigured or certain permissions for {{elastic-endpoint}} aren’t granted. The following sections explain issues that can cause warnings or failures in the endpoint’s policy status. + + +### Connect Kernel has failed [_connect_kernel_has_failed] + +This means that the system extension or kernel extension was not approved. Consult the following topics for approving the system extension with or without MDM: + +* [Approve the system extension with MDM](../../../solutions/security/configure-elastic-defend/deploy-on-macos-with-mdm.md#system-extension-jamf) +* [Approve the system extension without MDM](../../../solutions/security/configure-elastic-defend/enable-access-for-macos-monterey.md#system-extension-endpoint) + +You can validate the system extension is loaded by running: + +```shell +sudo systemextensionsctl list | grep co.elastic.systemextension +``` + +In the command output, the system extension should be marked as "active enabled". + + +### Connect Kernel has failed and the system extension is loaded [_connect_kernel_has_failed_and_the_system_extension_is_loaded] + +If the system extension is loaded and kernel connection still fails, this means that Full Disk Access was not granted. {{elastic-endpoint}} requires Full Disk Access to subscribe to system events through the {{elastic-defend}} framework, which is one of the primary sources of eventing information used by {{elastic-endpoint}}. Consult the following topics for granting Full Disk Access with or without MDM: + +* [Enable Full Disk Access with MDM](../../../solutions/security/configure-elastic-defend/deploy-on-macos-with-mdm.md#fda-jamf) +* [Enable Full Disk Access without MDM](../../../solutions/security/configure-elastic-defend/enable-access-for-macos-ventura-higher.md#enable-fda-endpoint-ven) + +You can validate that Full Disk Access is approved by running + +```shell +sudo /Library/Elastic/Endpoint/elastic-endpoint test install +``` + +If the command output doesn’t contain a message about enabling Full Disk Access, the approval was successful. + + +### Detect Network Events has failed [_detect_network_events_has_failed] + +This means that the network extension content filtering was not approved. Consult the following topics for approving network content filtering with or without MDM: + +* [Approve network content filtering with MDM](../../../solutions/security/configure-elastic-defend/deploy-on-macos-with-mdm.md#content-filtering-jamf) +* [Approve network content filtering without MDM](../../../solutions/security/configure-elastic-defend/enable-access-for-macos-ventura-higher.md#allow-filter-content-ven) + +You can validate that network content filtering is approved by running + +```shell +sudo /Library/Elastic/Endpoint/elastic-endpoint test install +``` + +If the command output doesn’t contain a message about approving network content filtering, the approval was successful. + + +### Full Disk Access has a warning [_full_disk_access_has_a_warning] + +This means that Full Disk Access was not granted for one or all {{elastic-endpoint}} components. Consult the following topics for granting Full Disk Access with or without MDM: + +* [Enable Full Disk Access with MDM](../../../solutions/security/configure-elastic-defend/deploy-on-macos-with-mdm.md#fda-jamf) +* [Enable Full Disk Access without MDM](../../../solutions/security/configure-elastic-defend/enable-access-for-macos-ventura-higher.md#enable-fda-endpoint-ven) + +You can validate that Full Disk Access is approved by running + +```shell +sudo /Library/Elastic/Endpoint/elastic-endpoint test install +``` + +If the command output doesn’t contain a message about enabling Full Disk Access, the approval was successful. + +:::: + + +::::{dropdown} Disable {{elastic-defend}}'s self-healing feature on Windows +:name: disable-self-healing + + +### Volume Snapshot Service issues [self-healing-vss-issues] + +{{elastic-defend}}'s self-healing feature rolls back recent filesystem changes when a prevention alert is triggered. This feature uses the Windows Volume Snapshot Service. Although it’s uncommon for this to cause issues, you can turn off this {{elastic-defend}} feature if needed. + +If issues occur and the self-healing feature is enabled, you can turn it off by setting `windows.advanced.alerts.rollback.self_healing.enabled` to `false` in the integration policy advanced settings. Refer to [Configure self-healing rollback for Windows endpoints](../../../solutions/security/configure-elastic-defend/configure-self-healing-rollback-for-windows-endpoints.md) for more information. + +{{elastic-defend}} may also use the Volume Snapshot Service to ensure the feature works properly even when it’s turned off. To opt out of this, set `windows.advanced.diagnostic.rollback_telemetry_enabled` to `false` in the same settings. + + +### Known compatibility issues [self-healing-compatibility-issues] + +There are some known compatibility issues between {{elastic-defend}}'s self-healing feature and filesystem replication features, including [DFS Replication](https://learn.microsoft.com/en-us/windows-server/storage/dfs-replication/dfsr-overview) and Veeam Replication. This may manifest as `DFSR Event ID 1102`: + +`The DFS Replication service has temporarily stopped replication because another application is performing a backup or restore operation. Replication will resume after the backup or restore operation has finished.` + +There are no known workarounds for this issue other than to turn off the self-healing feature. + +:::: \ No newline at end of file diff --git a/docs/migration/guide/bug-bash.md b/docs/migration/guide/bug-bash.md deleted file mode 100644 index 4387475fa..000000000 --- a/docs/migration/guide/bug-bash.md +++ /dev/null @@ -1,58 +0,0 @@ -# Build migrated content sets for Bug Bashes - -The following content sets are available for pre-migration testing: - -* [elasticsearch.md](https://github.com/elastic/elasticsearch.md) -* [integration-docs.md](https://github.com/elastic/integration-docs.md) -* [kibana.md](https://github.com/elastic/kibana.md) -* [logstash.md](https://github.com/elastic/logstash.md) -* [machine-learning.md](https://github.com/elastic/machine-learning.md) -* [observability-docs.md](https://github.com/elastic/observability-docs.md) - -## Local directory structure - -Assuming the following directory structure: - -```markdown -{GitHub_Repo_Dir}/ -├── tools/ -│ ├── docs-builder-mac-arm64.zip -│ └── docs-builder -├── elasticsearch.md -├── observability-docs.md -└── kibana.md -``` - -You can build migrated content sets on a Mac by running the following commands. - -```{tip} -For other systems, see [Contribute locally](../../contribute/locally.md) -``` - -```bash -# move to GitHub dir -cd {GitHub_Repo_Dir} - -# clone req'd repos -git clone https://github.com/elastic/elasticsearch.md.git -git clone https://github.com/elastic/observability-docs.md.git -git clone https://github.com/elastic/kibana.md.git - -# move back to GitHub dir -cd {GitHub_Repo_Dir} -mkdir tools -cd tools - -# mac-specific -curl -LO https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-mac-arm64.zip -unzip docs-builder-mac-arm64.zip - -# Build ES Guide -./docs-builder serve -p ../elasticsearch.md/docs - -# Build Obs Guide -./docs-builder serve -p ../observability-docs.md/docs - -# Build Kib Guide -./docs-builder serve -p ../kibana.md/docs -``` \ No newline at end of file diff --git a/docs/migration/guide/file-structure.md b/docs/migration/guide/file-structure.md index 12b842842..7f20f8087 100644 --- a/docs/migration/guide/file-structure.md +++ b/docs/migration/guide/file-structure.md @@ -5,55 +5,3 @@ In both the AsciiDoc- and V3-based systems, file structure is largely independen ## File and directory structure AsciiDoc files and assets (like images and videos) can be stored anywhere within the directories provided as `sources` for a given book in the central [`config.yaml` file in the /docs repo](https://github.com/elastic/docs/blob/master/conf.yaml). - -## Migration tool output - -The migration tool will add all MD files in a single directory. There will be one MD file for each web page in the migrated book. The name of each MD file and the URL in the new docs system are both derived from the URL of the AsciiDoc-built page. - -**Example:** Here's what happens with the -[Spans](https://www.elastic.co/guide/en/apm/guide/current/data-model-spans.html) page -in the APM docs: - -* **Old URL**: The URL for the page in the old system is: - `https://www.elastic.co/guide/en/apm/guide/current/data-model-spans.html`. - From the URL, we can determine the: - * _base URL_: `https://www.elastic.co/guide` - * _book ID_: `en/apm/guide` - * _version_: `current` - * _page ID_: `data-model-spans` -* **New filename**: The page ID determines the filename of the migrated MD file: -% `data-model-spans.mdx`. This file will be in the root directory of the directory containing the content for the `en/apm/guide` book. -* **New URL**: The new URL for this page in the new docs system will be `xxxx`. - -Because a single AsciiDoc file can contain the content for multiple pages (or content -displayed on a single page could be spread across multiple AsciiDoc files), the `.asciidoc` -filename can be different than the `.md` filename. However, you should be able to locate -the source content if you know which web page it lives on. - -In the output from the migration tool the slug (for example, `en/apm/guide/data-model-spans`) -and the MD filename (for example, `data-model-spans.md`) are both derived from -the page ID, they don't _have_ to be the same. - -### Assets - -The migration tool creates an `images/` directory in the base directory for the doc set. -Inside the `images/` directory, there is subdirectory for each page ID that contains images. - -For example, the images that are used on the [Entity Analytics dashboard](https://www.elastic.co/guide/en/security/current/detection-entity-dashboard.html) page in the AsciiDoc Security book would be copied to -the following location in the migrated docs: - -``` -images - └─ detection-entity-dashboard - ├─ dashboards-anomalies-table.png - ├─ dashboards-entity-dashboard.png - ├─ dashboards-host-score-data.png - ├─ dashboards-run-job.png - └─ dashboards-user-score-data.png -``` - -These can be reorganized post-migration. - -### Reusable content - -Reusable content is lost during migration. \ No newline at end of file diff --git a/docs/migration/guide/index.md b/docs/migration/guide/index.md index 4bf60cce5..fc347a911 100644 --- a/docs/migration/guide/index.md +++ b/docs/migration/guide/index.md @@ -1,7 +1,11 @@ # Migration Guide -Migrate content from Asciidoc to V3 +How do I migrate content? How do I work with migrated content? What's actually moving? -* [Migrate automated documentation](./automated.md) — for developers -* [Migrate narrative content manually](./tooling.md) — handled by the docs team -* [Build pre-migrated content sets](./bug-bash.md) — for the docs team bug bash \ No newline at end of file +_For writers_ --> [**How to work in `elastic/docs-content`**](./working-in-docs-content.md) + +_For developers_ --> [**How to migrate automated documentation**](./automated.md) + +_For the migration team_ --> [**How to migrate narrative content**](./tooling.md) + +_For the generally curious_ --> [**What books were migrated?**](./mapping.md) \ No newline at end of file diff --git a/docs/migration/guide/mapping.md b/docs/migration/guide/mapping.md index bb17fa94f..171f60a7f 100644 --- a/docs/migration/guide/mapping.md +++ b/docs/migration/guide/mapping.md @@ -1,131 +1,9 @@ --- -navigation_title: What books are migrating +navigation_title: What books were migrated? --- -# Book to content set mapping +# What books were migrated? -What full books are staying in Asciidoc? What books are migrating `main`/`master`? See the table below. +We did not migrate all Elastic documentation. We are purposefully leaving the majority of content behind in the legacy Asciidoc build system. This system will turn into our documentation archive. -| Title | Current Version | Sources | Migrate to | -|----------------------------------------------------------------------------------------------------------|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------- | -| **Search UI** | main | [search-ui](https://github.com/elastic/search-ui.git) | | -| **Integrations** | main | [integration-docs](https://github.com/elastic/integration-docs.git) | | -| **Serverless** | main | [docs-content](https://github.com/elastic/docs-content.git), [observability-docs](https://github.com/elastic/observability-docs.git), [security-docs](https://github.com/elastic/security-docs.git) | | -| **Elasticsearch Guide** | 8.17 | [elasticsearch](https://github.com/elastic/elasticsearch.git), [x-pack-elasticsearch](https://github.com/elastic/x-pack-elasticsearch.git), [elasticsearch-php](https://github.com/elastic/elasticsearch-php.git), [elasticsearch-py](https://github.com/elastic/elasticsearch-py.git), [go-elasticsearch](https://github.com/elastic/go-elasticsearch.git), [elasticsearch-ruby](https://github.com/elastic/elasticsearch-ruby.git), [elasticsearch-js](https://github.com/elastic/elasticsearch-js.git) | | -| **Enterprise Search Guide** | 8.17 | [enterprise-search-pubs](https://github.com/elastic/enterprise-search-pubs.git), [docs](https://github.com/elastic/docs.git) | | -| **Workplace Search Guide** | 8.17 | [enterprise-search-pubs](https://github.com/elastic/enterprise-search-pubs.git), [docs](https://github.com/elastic/docs.git) | | -| **App Search Guide** | 8.17 | [enterprise-search-pubs](https://github.com/elastic/enterprise-search-pubs.git), [docs](https://github.com/elastic/docs.git) | | -| **App Search JavaScript client** | 8.17 | [enterprise-search-pubs](https://github.com/elastic/enterprise-search-pubs.git), [docs](https://github.com/elastic/docs.git) | | -| **App Search Node.js client** | 8.17 | [enterprise-search-pubs](https://github.com/elastic/enterprise-search-pubs.git), [docs](https://github.com/elastic/docs.git) | | -| **Enterprise Search Node.js client** | 8.17 | [enterprise-search-js](https://github.com/elastic/enterprise-search-js.git), [docs](https://github.com/elastic/docs.git) | | -| **Enterprise Search PHP client** | 8.17 | [enterprise-search-php](https://github.com/elastic/enterprise-search-php.git), [docs](https://github.com/elastic/docs.git) | | -| **Enterprise Search Python client** | 8.17 | [enterprise-search-python](https://github.com/elastic/enterprise-search-python.git), [docs](https://github.com/elastic/docs.git) | | -| **Enterprise Search Ruby client** | 8.17 | [enterprise-search-ruby](https://github.com/elastic/enterprise-search-ruby.git), [docs](https://github.com/elastic/docs.git) | | -| **Workplace Search Node.js client** | 8.17 | [enterprise-search-pubs](https://github.com/elastic/enterprise-search-pubs.git), [docs](https://github.com/elastic/docs.git) | | -| **Observability** | 8.17 | [observability-docs](https://github.com/elastic/observability-docs.git), [ingest-docs](https://github.com/elastic/ingest-docs.git), [apm-server](https://github.com/elastic/apm-server.git), [beats](https://github.com/elastic/beats.git), [docs](https://github.com/elastic/docs.git) | | -| **APM Guide** | 8.17 | [observability-docs](https://github.com/elastic/observability-docs.git), [apm-server](https://github.com/elastic/apm-server.git), [ingest-docs](https://github.com/elastic/ingest-docs.git) | | -| **APM Android Agent** | 0.x | [apm-agent-android](https://github.com/elastic/apm-agent-android.git) | | -| **APM Go Agent** | 2.x | [apm-agent-go](https://github.com/elastic/apm-agent-go.git) | | -| **APM iOS Agent** | 1.x | [apm-agent-ios](https://github.com/elastic/apm-agent-ios.git) | | -| **APM Java Agent** | 1.x | [apm-agent-java](https://github.com/elastic/apm-agent-java.git), [apm-aws-lambda](https://github.com/elastic/apm-aws-lambda.git) | | -| **APM .NET Agent** | 1.x | [apm-agent-dotnet](https://github.com/elastic/apm-agent-dotnet.git) | | -| **APM Node.js Agent** | 4.x | [apm-agent-nodejs](https://github.com/elastic/apm-agent-nodejs.git), [apm-aws-lambda](https://github.com/elastic/apm-aws-lambda.git) | | -| **APM PHP Agent** | 1.x | [apm-agent-php](https://github.com/elastic/apm-agent-php.git) | | -| **APM Python Agent** | 6.x | [apm-agent-python](https://github.com/elastic/apm-agent-python.git), [apm-aws-lambda](https://github.com/elastic/apm-aws-lambda.git) | | -| **APM Ruby Agent** | 4.x | [apm-agent-ruby](https://github.com/elastic/apm-agent-ruby.git) | | -| **APM Real User Monitoring JavaScript Agent** | 5.x | [apm-agent-rum-js](https://github.com/elastic/apm-agent-rum-js.git) | | -| **APM AWS Lambda Extension** | main | [apm-aws-lambda](https://github.com/elastic/apm-aws-lambda.git) | | -| **APM Attacher** | main | [apm-k8s-attacher](https://github.com/elastic/apm-k8s-attacher.git) | | -| **ECS Logging Overview** | main | [ecs-logging](https://github.com/elastic/ecs-logging.git), [docs](https://github.com/elastic/docs.git) | | -| **ECS Logging Go (Logrus) Reference** | main | [ecs-logging-go-logrus](https://github.com/elastic/ecs-logging-go-logrus.git), [ecs-logging](https://github.com/elastic/ecs-logging.git), [docs](https://github.com/elastic/docs.git) | | -| **ECS Logging Go (Zap) Reference** | main | [ecs-logging-go-zap](https://github.com/elastic/ecs-logging-go-zap.git), [ecs-logging](https://github.com/elastic/ecs-logging.git), [docs](https://github.com/elastic/docs.git) | | -| **ECS Logging Go (zerolog) Reference** | main | [ecs-logging-go-zerolog](https://github.com/elastic/ecs-logging-go-zerolog.git), [ecs-logging](https://github.com/elastic/ecs-logging.git), [docs](https://github.com/elastic/docs.git) | | -| **ECS Logging Java Reference** | 1.x | [ecs-logging-java](https://github.com/elastic/ecs-logging-java.git), [ecs-logging](https://github.com/elastic/ecs-logging.git), [docs](https://github.com/elastic/docs.git) | | -| **ECS Logging .NET Reference** | main | [ecs-dotnet](https://github.com/elastic/ecs-dotnet.git), [ecs-logging](https://github.com/elastic/ecs-logging.git), [docs](https://github.com/elastic/docs.git) | | -| **ECS Logging Node.js Reference** | main | [ecs-logging-nodejs](https://github.com/elastic/ecs-logging-nodejs.git), [ecs-logging](https://github.com/elastic/ecs-logging.git), [docs](https://github.com/elastic/docs.git) | | -| **ECS Logging Ruby Reference** | main | [ecs-logging-ruby](https://github.com/elastic/ecs-logging-ruby.git), [ecs-logging](https://github.com/elastic/ecs-logging.git), [docs](https://github.com/elastic/docs.git) | | -| **ECS Logging PHP Reference** | main | [ecs-logging-php](https://github.com/elastic/ecs-logging-php.git), [ecs-logging](https://github.com/elastic/ecs-logging.git), [docs](https://github.com/elastic/docs.git) | | -| **ECS Logging Python Reference** | main | [ecs-logging-python](https://github.com/elastic/ecs-logging-python.git), [ecs-logging](https://github.com/elastic/ecs-logging.git), [docs](https://github.com/elastic/docs.git) | | -| **Elastic Security** | 8.17 | [security-docs](https://github.com/elastic/security-docs.git), [docs](https://github.com/elastic/docs.git), [stack-docs](https://github.com/elastic/stack-docs.git) | | -| **Starting with the Elasticsearch Platform and its Solutions** | 8.17 | [tech-content](https://github.com/elastic/tech-content.git), [docs](https://github.com/elastic/docs.git) | | -| **Curator Index Management** | 8.0 | [curator](https://github.com/elastic/curator.git) | | -| **Elastic Common Schema (ECS) Reference** | 8.16 | [ecs](https://github.com/elastic/ecs.git) | | -| **Java Client** | 8.17 | [elasticsearch-java](https://github.com/elastic/elasticsearch-java.git), [elasticsearch](https://github.com/elastic/elasticsearch.git) | | -| **JavaScript Client** | 8.17 | [elasticsearch-js](https://github.com/elastic/elasticsearch-js.git) | | -| **Ruby Client** | 8.17 | [elasticsearch-ruby](https://github.com/elastic/elasticsearch-ruby.git) | | -| **Go Client** | 8.17 | [go-elasticsearch](https://github.com/elastic/go-elasticsearch.git) | | -| **.NET Clients** | 8.17 | [elasticsearch-net](https://github.com/elastic/elasticsearch-net.git) | | -| **PHP Client** | 8.17 | [elasticsearch-php](https://github.com/elastic/elasticsearch-php.git), [docs](https://github.com/elastic/docs.git) | | -| **Perl Client** | master | [elasticsearch-perl](https://github.com/elastic/elasticsearch-perl.git) | | -| **Python Client** | 8.17 | [elasticsearch-py](https://github.com/elastic/elasticsearch-py.git) | | -| **eland** | main | [eland](https://github.com/elastic/eland.git) | | -| **Rust Client** | main | [elasticsearch-rs](https://github.com/elastic/elasticsearch-rs.git) | | -| **Java REST Client (deprecated)** | 7.17 | [elasticsearch](https://github.com/elastic/elasticsearch.git), [docs](https://github.com/elastic/docs.git) | | -| **Java Transport Client (deprecated)** | 7.17 | [elasticsearch](https://github.com/elastic/elasticsearch.git), [docs](https://github.com/elastic/docs.git) | | -| **Community Contributed Clients** | main | [elasticsearch](https://github.com/elastic/elasticsearch.git) | | -| **Elasticsearch for Apache Hadoop and Spark** | 8.17 | [elasticsearch-hadoop](https://github.com/elastic/elasticsearch-hadoop.git) | | -| **Elasticsearch Relevance Engine (ESRE)** | 8.17 | [enterprise-search-pubs](https://github.com/elastic/enterprise-search-pubs.git), [docs](https://github.com/elastic/docs.git) | | -| **Glossary** | main | [stack-docs](https://github.com/elastic/stack-docs.git), [docs](https://github.com/elastic/docs.git) | | -| **Installation and Upgrade Guide** | 8.17 | [stack-docs](https://github.com/elastic/stack-docs.git), [apm-server](https://github.com/elastic/apm-server.git), [beats](https://github.com/elastic/beats.git), [elasticsearch](https://github.com/elastic/elasticsearch.git), [elasticsearch-hadoop](https://github.com/elastic/elasticsearch-hadoop.git), [security-docs](https://github.com/elastic/security-docs.git), [kibana](https://github.com/elastic/kibana.git), [logstash](https://github.com/elastic/logstash.git), [observability-docs](https://github.com/elastic/observability-docs.git), [docs](https://github.com/elastic/docs.git) | | -| **Kibana Guide** | 8.17 | [kibana](https://github.com/elastic/kibana.git), [docs](https://github.com/elastic/docs.git) | | -| **Machine Learning** | 8.17 | [stack-docs](https://github.com/elastic/stack-docs.git), [elasticsearch](https://github.com/elastic/elasticsearch.git), [docs](https://github.com/elastic/docs.git) | | -| **Painless Scripting Language** | 8.17 | [elasticsearch](https://github.com/elastic/elasticsearch.git), [docs](https://github.com/elastic/docs.git) | | -| **Plugins and Integrations** | 8.17 | [elasticsearch](https://github.com/elastic/elasticsearch.git), [docs](https://github.com/elastic/docs.git) | | -| **Reference Architectures** | main | [stack-docs](https://github.com/elastic/stack-docs.git), [docs](https://github.com/elastic/docs.git) | | -| **Elastic Ingest Reference Architectures** | 8.17 | [ingest-docs](https://github.com/elastic/ingest-docs.git), [docs](https://github.com/elastic/docs.git) | | -| **Fleet and Elastic Agent Guide** | 8.17 | [ingest-docs](https://github.com/elastic/ingest-docs.git), [observability-docs](https://github.com/elastic/observability-docs.git), [apm-server](https://github.com/elastic/apm-server.git), [docs](https://github.com/elastic/docs.git) | | -| **Logstash Reference** | 8.17 | [logstash](https://github.com/elastic/logstash.git), [logstash-docs](https://github.com/elastic/logstash-docs.git), [docs](https://github.com/elastic/docs.git) | | -| **Logstash Versioned Plugin Reference** | versioned_plugin_docs | [logstash-docs](https://github.com/elastic/logstash-docs.git), [docs](https://github.com/elastic/docs.git) | | -| **Elastic Logging Plugin for Docker** | 8.17 | [beats](https://github.com/elastic/beats.git), [docs](https://github.com/elastic/docs.git) | | -| **Elastic Serverless Forwarder Guide** | main | [elastic-serverless-forwarder](https://github.com/elastic/elastic-serverless-forwarder.git), [docs](https://github.com/elastic/docs.git) | | -| **Integrations Developer Guide** | main | [observability-docs](https://github.com/elastic/observability-docs.git), [docs](https://github.com/elastic/docs.git), [package-spec](https://github.com/elastic/package-spec.git) | | -| **Auditbeat Reference** | 8.17 | [beats](https://github.com/elastic/beats.git), [docs](https://github.com/elastic/docs.git) | | -| **Beats Developer Guide** | main | [beats](https://github.com/elastic/beats.git), [docs](https://github.com/elastic/docs.git) | | -| **Beats Platform Reference** | 8.17 | [beats](https://github.com/elastic/beats.git), [docs](https://github.com/elastic/docs.git) | | -| **Filebeat Reference** | 8.17 | [beats](https://github.com/elastic/beats.git), [docs](https://github.com/elastic/docs.git) | | -| **Heartbeat Reference** | 8.17 | [beats](https://github.com/elastic/beats.git), [docs](https://github.com/elastic/docs.git) | | -| **Metricbeat Reference** | 8.17 | [beats](https://github.com/elastic/beats.git), [docs](https://github.com/elastic/docs.git) | | -| **Packetbeat Reference** | 8.17 | [beats](https://github.com/elastic/beats.git), [docs](https://github.com/elastic/docs.git) | | -| **Winlogbeat Reference** | 8.17 | [beats](https://github.com/elastic/beats.git), [docs](https://github.com/elastic/docs.git) | | -| **Elastic Cloud, Hosted Elastic Stack** | ms-117 | [cloud](https://github.com/elastic/cloud.git) | | -| **Elasticsearch Add-On for Heroku - Hosted Elasticsearch and Kibana for Heroku Users** | ms-117 | [cloud](https://github.com/elastic/cloud.git) | | -| **Elastic Cloud Enterprise - Elastic Cloud on your Infrastructure** | ms-105 | [cloud](https://github.com/elastic/cloud.git), [cloud-assets](https://github.com/elastic/cloud-assets.git), [clients-team](https://github.com/elastic/clients-team.git), [docs](https://github.com/elastic/docs.git) | | -| **Elastic Cloud on Kubernetes** | 2.16 | [cloud-on-k8s](https://github.com/elastic/cloud-on-k8s.git), [docs](https://github.com/elastic/docs.git) | | -| **Elastic Cloud Control - The Command-Line Interface for Elasticsearch Service and ECE** | 1.14 | [ecctl](https://github.com/elastic/ecctl.git) | | -| **Elastic Cloud Terraform Provider** | master | [terraform-provider-ec](https://github.com/elastic/terraform-provider-ec.git) | | -| **Elastic Stack and Google Cloud's Anthos** | main | [stack-docs](https://github.com/elastic/stack-docs.git), [docs](https://github.com/elastic/docs.git) | **not migrating** | -| **Elasticsearch - The Definitive Guide** | 2.x | [elasticsearch-definitive-guide](https://github.com/elastic/elasticsearch-definitive-guide.git), [docs](https://github.com/elastic/docs.git) | **not migrating** | -| **Elasticsearch Resiliency Status** | main | [elasticsearch](https://github.com/elastic/elasticsearch.git), [docs](https://github.com/elastic/docs.git) | **not migrating** | -| **Elasticsearch.js for 5.6-7.6** | 16.x | [elasticsearch-js-legacy](https://github.com/elastic/elasticsearch-js-legacy.git) | **not migrating** | -| **Functionbeat Reference** | 8.15 | [beats](https://github.com/elastic/beats.git), [docs](https://github.com/elastic/docs.git) | **not migrating** | -| **Getting Started** | 8.2 | [stack-docs](https://github.com/elastic/stack-docs.git), [docs](https://github.com/elastic/docs.git), [elasticsearch](https://github.com/elastic/elasticsearch.git) | **not migrating** | -| **Graph Reference for 2.x** | 2.4 | [x-pack](https://github.com/elastic/x-pack.git), [docs](https://github.com/elastic/docs.git) | **not migrating** | -| **Groovy API** | 2.4 | [elasticsearch](https://github.com/elastic/elasticsearch.git) | **not migrating** | -| **Infrastructure Monitoring Guide for 6.5-7.4** | 7.4 | [stack-docs](https://github.com/elastic/stack-docs.git), [docs](https://github.com/elastic/docs.git) | **not migrating** | -| **Journalbeat Reference for 6.5-7.15** | 7.15 | [beats](https://github.com/elastic/beats.git), [docs](https://github.com/elastic/docs.git) | **not migrating** | -| **Legacy APM Overview** | 7.15 | [apm-server](https://github.com/elastic/apm-server.git) | **not migrating** | -| **Legacy APM Server Reference** | 7.15 | [apm-server](https://github.com/elastic/apm-server.git) | **not migrating** | -| **Logs Monitoring Guide for 7.5-7.9** | 7.9 | [observability-docs](https://github.com/elastic/observability-docs.git), [docs](https://github.com/elastic/docs.git) | **not migrating** | -| **Marvel Reference for 2.x and 1.x** | 2.4 | [x-pack](https://github.com/elastic/x-pack.git), [docs](https://github.com/elastic/docs.git) | **not migrating** | -| **Metrics Monitoring Guide for 7.5-7.9** | 7.9 | [observability-docs](https://github.com/elastic/observability-docs.git), [docs](https://github.com/elastic/docs.git) | **not migrating** | -| **Reporting Reference for 2.x** | 2.4 | [x-pack](https://github.com/elastic/x-pack.git) | **not migrating** | -| **Sense Editor for 4.x** | master | [sense](https://github.com/elastic/sense.git) | **not migrating** | -| **Shield Reference for 2.x and 1.x** | 2.4 | [x-pack](https://github.com/elastic/x-pack.git), [docs](https://github.com/elastic/docs.git) | **not migrating** | -| **SIEM Guide** | 7.8 | [stack-docs](https://github.com/elastic/stack-docs.git), [docs](https://github.com/elastic/docs.git) | **not migrating** | -| **Site Search Reference** | master | [swiftype-doc-placeholder](https://github.com/elastic/swiftype-doc-placeholder.git) | **not migrating** | -| **Topbeat Reference** | 1.3 | [beats](https://github.com/elastic/beats.git) | **not migrating** | -| **Uptime Monitoring Guide for 7.2-7.9** | 7.9 | [observability-docs](https://github.com/elastic/observability-docs.git), [docs](https://github.com/elastic/docs.git) | **not migrating** | -| **Stack Overview** | 7.4 | [stack-docs](https://github.com/elastic/stack-docs.git), [docs](https://github.com/elastic/docs.git) | **not migrating** | -| **Watcher Reference for 2.x and 1.x** | 2.4 | [x-pack](https://github.com/elastic/x-pack.git), [docs](https://github.com/elastic/docs.git) | **not migrating** | -| **X-Pack Reference for 6.0-6.2 and 5.x** | 6.2 | [x-pack](https://github.com/elastic/x-pack.git), [x-pack-kibana](https://github.com/elastic/x-pack-kibana.git), [x-pack-elasticsearch](https://github.com/elastic/x-pack-elasticsearch.git), [docs](https://github.com/elastic/docs.git) | **not migrating** | -| **《Elasticsearch 权威指南》中文版** | cn | [elasticsearch-definitive-guide](https://github.com/elasticsearch-cn/elasticsearch-definitive-guide.git) | **not migrating** | -| **PHP API** | cn | [elasticsearch-php](https://github.com/elasticsearch-cn/elasticsearch-php.git) | **not migrating** | -| **Kibana 用户手册** | cn | [kibana](https://github.com/elasticsearch-cn/kibana.git) | **not migrating** | -| **Elasticsearchリファレンス** | 5.4 | [elasticsearch](https://github.com/elastic/elasticsearch.git) | **not migrating** | -| **Logstashリファレンス** | 5.4 | [logstash](https://github.com/elastic/logstash.git) | **not migrating** | -| **Kibanaユーザーガイド** | 5.4 | [kibana](https://github.com/elastic/kibana.git) | **not migrating** | -| **X-Packリファレンス** | 5.4 | [x-pack](https://github.com/elastic/x-pack.git), [x-pack-kibana](https://github.com/elastic/x-pack-kibana.git), [x-pack-elasticsearch](https://github.com/elastic/x-pack-elasticsearch.git) | **not migrating** | -| **Elasticsearch 참조** | 5.4 | [elasticsearch](https://github.com/elastic/elasticsearch.git) | **not migrating** | -| **Logstash 참조** | 5.4 | [logstash](https://github.com/elastic/logstash.git) | **not migrating** | -| **Kibana 사용자 가이드** | 5.4 | [kibana](https://github.com/elastic/kibana.git) | **not migrating** | -| **X-Pack 참조** | 5.4 | [x-pack](https://github.com/elastic/x-pack.git), [x-pack-kibana](https://github.com/elastic/x-pack-kibana.git), [x-pack-elasticsearch](https://github.com/elastic/x-pack-elasticsearch.git) | **not migrating** | +A full list of the content that was migrated to the V3 format is available [here](https://github.com/elastic/asciidocalypse/blob/main/docs/readme.md). \ No newline at end of file diff --git a/docs/migration/guide/tooling.md b/docs/migration/guide/tooling.md index 3f2cb0457..3376176f6 100644 --- a/docs/migration/guide/tooling.md +++ b/docs/migration/guide/tooling.md @@ -1,11 +1,67 @@ -# Run migration tooling +--- +navigation_title: Migrate narrative docs +--- + +# Migrate narrative docs + +:::{important} +Migration tooling has already been run. This documentation will be removed at a future date. +::: Use the [adoc-to-md](https://github.com/elastic/adoc-to-md) conversion tool to migrate content sets from Asciidoc syntax to docs-builder syntax. Instructions to use the tool are in the readme file. +### Migration tool output + +The migration tool will add all MD files in a single directory. There will be one MD file for each web page in the migrated book. The name of each MD file and the URL in the new docs system are both derived from the URL of the AsciiDoc-built page. + +**Example:** Here's what happens with the [Spans](https://www.elastic.co/guide/en/apm/guide/current/data-model-spans.html) page in the APM docs: + +* **Old URL**: The URL for the page in the old system is: + `https://www.elastic.co/guide/en/apm/guide/current/data-model-spans.html`. + From the URL, we can determine the: + * _base URL_: `https://www.elastic.co/guide` + * _book ID_: `en/apm/guide` + * _version_: `current` + * _page ID_: `data-model-spans` +* **New filename**: The page ID determines the filename of the migrated MD file: +% `data-model-spans.mdx`. This file will be in the root directory of the directory containing the content for the `en/apm/guide` book. +* **New URL**: The new URL for this page in the new docs system will be `xxxx`. + +Because a single AsciiDoc file can contain the content for multiple pages (or content +displayed on a single page could be spread across multiple AsciiDoc files), the `.asciidoc` +filename can be different than the `.md` filename. However, you should be able to locate +the source content if you know which web page it lives on. + +In the output from the migration tool the slug (for example, `en/apm/guide/data-model-spans`) +and the MD filename (for example, `data-model-spans.md`) are both derived from +the page ID, they don't _have_ to be the same. + +### Assets + +The migration tool creates an `images/` directory in the base directory for the doc set. +Inside the `images/` directory, there is subdirectory for each page ID that contains images. + +For example, the images that are used on the [Entity Analytics dashboard](https://www.elastic.co/guide/en/security/current/detection-entity-dashboard.html) page in the AsciiDoc Security book would be copied to +the following location in the migrated docs: + +``` +images + └─ detection-entity-dashboard + ├─ dashboards-anomalies-table.png + ├─ dashboards-entity-dashboard.png + ├─ dashboards-host-score-data.png + ├─ dashboards-run-job.png + └─ dashboards-user-score-data.png +``` + +### Reusable content + +Reusable content is lost during migration. + ## Post-migration tooling -After migrating content from asciidoc to md, there is cleanup work to do. @colleen has created a script to handle this process for us. The script: +After migrating content from asciidoc to md, there is cleanup work to do. Ccolleen has created a script to handle this process for us. The script: * Moves files to their new home in the new IA * Nests content at a pre-selected depth @@ -19,8 +75,8 @@ After migrating content from asciidoc to md, there is cleanup work to do. @colle ## Post-migration manual work -* Being tracked in https://github.com/elastic/docs-builder/issues/261 +* Being tracked in [#261](https://github.com/elastic/docs-builder/issues/261). ## What's next? -After running the migration tool, you can move and manipulate files while viewing a live preview of the content with docs-builder. \ No newline at end of file +After running the migration tool, you can move and manipulate files while viewing a live preview of the content with docs-builder. See [working in docs-content](./working-in-docs-content.md) for more information. \ No newline at end of file diff --git a/docs/migration/guide/working-in-docs-content.md b/docs/migration/guide/working-in-docs-content.md new file mode 100644 index 000000000..0b9eda512 --- /dev/null +++ b/docs/migration/guide/working-in-docs-content.md @@ -0,0 +1,91 @@ +# Working in docs-content + +## What’s included in the initial migrated content set + +To start, you will only have access to pages in the `get-started`, `solutions`, `manage-data`, `explore-analyze`, `deploy-manage`, and `troubleshoot` sections. The migrated `reference`, `release-notes`, and `extend` content will be available in the next few days. As a result, any links to pages in the `reference`, `release-notes`, and `extend` sections will be absolute links to the legacy AsciiDoc page. We will update links to these sections when the content is ready to be migrated to its forever home. + +## How to navigate the migrated files in docs-content + +How the migrated content for each page is organized in the new IA depends on how you filled out [Elastic docs IA](https://docs.google.com/spreadsheets/d/1LfPI3TZqdpONGxOmL8B8V-Feo1flLwObz9_ibCEMkIQ/edit?gid=502629814#gid=502629814). + +**Frontmatter** +In Markdown files, there are two possible frontmatter options: + +* **`navigation_title`**: This was added automatically if the AsciiDoc file that was migrated used `titleabbrev`. +* **`mapped_pages`**: This is a list of the AsciiDoc pages that are mapped to the new v3 page. **It is very important that you do not remove `mapped_pages` from the Markdown files** unless you’re moving the AsciiDoc page to a different v3 page’s list of `mapped_pages`. This is how we will keep track of the redirects we need to create when we end the documentation freeze. + +**One-to-one mapping** +If there was just one AsciiDoc page mapped to the new v3 page, the migrated content was copied into a new Markdown file in its correct place in the new IA. + +**Many-to-one mapping** +If there were multiple AsciiDoc pages mapped to a new v3 page: + +* A stub Markdown file was added to its correct place in the new IA. This includes context from the IA inventory, including: + * What needs to be done + * Any scope notes + * Linked GitHub issues + * A list of migrated files to pull from when you’re building out the stub page + * A list of any IDs (heading ID, paragraph ID, etc) that are necessary for internal links to work. As you start editing these files, you’ll need to incorporate these IDs or remove/update the links that point to these IDs. +* The migrated content from all the AsciiDoc pages mapped to the page are saved in the `raw-migrated-files` directory. That directory is organized by source repo and book (for example, a migrated file from the Security book will be in `raw-migrated-files/security-docs/security/`). These pages also appear in the rendered doc site at the bottom of the table of contents under *Content to pull from*. + +**Zero-to-one mapping** +If there were no AsciiDoc pages mapped to the new v3 page, a stub file was created in its correct place in the new IA with any scope notes you added to the IA inventory. These pages won’t have `mapped_pages` in the frontmatter. + +**Navigation files** +There are two types of navigation files: + +* **`docset.yml`**: There is one doc set configuration file that compiles all the section `toc.yml` files. +* **`toc.yml`**: There is a table of contents file for each section. + +**Images** +Images are in [one directory](https://github.com/elastic/docs-content/tree/main/images) at the top level of the docs-content repo. Please keep all images in this directory for now. We need to come up with a long-term strategy for images in this repository before making any changes. + +## Dos and Don’ts + +**It’s ok to:** + +* Rename files and directories and move files between directories. Be sure to update links and image references when moving content. + * We recommend using the `docs-builder mv` command to move files or folders. This command will move a single file or folder and automatically update any links for you. Use the command with: + + `docs-builder mv ./old-location/ia.md ./new-location/ia.md` + +* More details on the `mv` command are in [https://github.com/elastic/docs-builder/pull/376](https://github.com/elastic/docs-builder/pull/376). +* Change the `h1` title. +* Change the `navigation_title` in the frontmatter. +* Add the [product availability](https://elastic.github.io/docs-builder/syntax/applies.html) to frontmatter of each page. +* Make edits to the migrated content. +* Copy content from `raw-migrated-files` into the stub page files. Be sure to update links and image references when moving content. + * Check if any other pages rely on the content in the `raw-migrated-files` file. You can either: + * Refer to the [IA inventory](https://docs.google.com/spreadsheets/d/1LfPI3TZqdpONGxOmL8B8V-Feo1flLwObz9_ibCEMkIQ/edit?gid=605983744#gid=605983744). + * Search across the docs-content repo for the name of the file to see if it shows up in other stub pages. + * If no other pages rely on this file, delete the file from the `raw-migrated-files` directory. + * If other pages do rely on this file, add a code comment to the file in the `raw-migrated-files` directory letting other writers know what content you used in the file. +* Report v3 bugs in [elastic/docs-builder](https://github.com/elastic/docs-builder/issues). + +**Do not**: + +* Remove the `mapped_pages` frontmatter. +* Nest Markdown files more than 3 levels deep within the docs-content repo. This has implications for URLs and SEO. +* Delete any IDs listed on stub pages without updating links that point to them throughout the docs. + +## How to open a pull request + +You must propose changes on a branch pushed to the upstream (elastic/docs-content) repository, not a personal clone. + +When you open a PR to update files in docs-content, the `docs-preview/deploy` action will run. This action will build your PR and ensure your changes don’t introduce errors (like broken links). If the build succeeds, click *View deployment* to see a preview of your changes. + +If the build fails, open the GitHub action to view the errors. You will not be able to merge your PR until all errors are resolved. + +## Open `docs-builder` bugs and enhancements + +As you start diving into the new system, you’ll likely encounter bugs or things that are missing that you’d like to see. + +### Bugs + +For bugs, open an issue [here](https://github.com/elastic/docs-builder/issues/new?template=bug-report.yaml). + +### Feature requests + +For feature requests, we’re now using GitHub Discussions. You can open a feature request [here](https://github.com/elastic/docs-builder/discussions/new?category=feature-request). We’re making the switch to Discussions because they offer a better way to brainstorm and gather feedback in a collaborative, async-friendly way (like threaded conversations for easier back-and-forth). + +Please check out the growing list of feature requests from your fellow writers [here](https://github.com/elastic/docs-builder/discussions/new?category=feature-request). Vote on enhancements, share your thoughts, and add any ideas you have. Your feedback is crucial to ensure we’re prioritizing the right features and building the best system possible. diff --git a/docs/migration/index.md b/docs/migration/index.md index f9d4af785..d9749743a 100644 --- a/docs/migration/index.md +++ b/docs/migration/index.md @@ -2,19 +2,17 @@ navigation_title: Migration --- -# "Migration to docs-builder" - -We are ready to migrate our documentation to our new build system, [elastic/docs-builder](https://github.com/elastic/docs-builder)! +# Migration to docs-builder :::{important} -We will enforce a [Documentation Freeze](./freeze/index.md) while we migrate docs between our two build systems. +We are enforcing a [Documentation Freeze](./freeze/index.md) while we migrate docs between our two build systems. ::: -Migrating to Elastic Docs V3 is more than just moving to a new documentation build system. This migration also includes: +Migrating to Elastic Docs V3 is more than just moving to a new documentation build system. This migration includes: -* [Transition from AsciiDoc to Markdown](./syntax.md) -* [Improved information architecture](./ia.md) -* [Consolidated versioning](./versioning.md) -* [Engineering ownership of reference documentation & New API guidelines](./engineering.md) +* [New syntax](./syntax.md): from AsciiDoc to Markdown +* [New information architecture (IA)](./ia.md): aligning docs around user goals, not internal org structure +* [New versioning](./versioning.md): consolidation from many to one +* [New reference guidelines](./engineering.md): Engineering ownership of reference documentation & New API guidelines View the [migration guide](./guide/index.md) to learn more about migration tooling, what content sets are migrating, how to migrate content, and more. \ No newline at end of file diff --git a/docs/migration/versioning.md b/docs/migration/versioning.md index 1adcc4fea..4b7106344 100644 --- a/docs/migration/versioning.md +++ b/docs/migration/versioning.md @@ -1,4 +1,4 @@ -# Consolidated versioning +# New versioning As part of the new information architecture, pages with varying versioning schemes are now interwoven, creating the opportunity and necessity to rethink the scope and versioning of each page. The previous approach of creating entirely separate docs sets for every minor version resulted in fragmentation and unnecessary duplication. Consolidating versioning resolves these issues while maintaining clarity and usability. diff --git a/docs/syntax/admonitions.md b/docs/syntax/admonitions.md index 1a001a957..703f43008 100644 --- a/docs/syntax/admonitions.md +++ b/docs/syntax/admonitions.md @@ -13,26 +13,6 @@ Available admonition types include: - Important - Plain -### Plain - -A plain admonition is a callout with no further styling. Useful to create a callout that does not quite fit the mold of the stylized admonitions - -```markdown -:::{admonition} This is my callout - -It can *span* multiple lines and supports inline formatting. - -::: -``` - -:::{admonition} This is my callout - -It can *span* multiple lines and supports inline formatting. - -::: - - - ### Note A relevant piece of information with no serious repercussions if ignored. @@ -90,10 +70,24 @@ This is an important notice. This is an important notice. ::: +### Plain + +A plain admonition is a callout with no further styling. Useful to create a callout that does not quite fit the mold of the stylized admonitions. + +```markdown +:::{admonition} This is my callout +It can *span* multiple lines and supports inline formatting. +::: +``` + +:::{admonition} This is my callout +It can *span* multiple lines and supports inline formatting. +::: + ## Collapsible admonitions -:::{tip} -Also see [dropdowns](./dropdowns.md). +:::{warning} +Collapsible admonitions are deprecated. Do not use them. Use [dropdowns](./dropdowns.md) instead. ::: Use `:open: ` to make an admonition collapsible. @@ -115,26 +109,3 @@ Longer content can be collapsed to take less space. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. ::: - ---- - -## Asciidoc Syntax - -### Inline Admonition - -```markdown -NOTE: This is a note. -It can be multiple lines, but not multiple paragraphs. -``` - -### Block Admonition - -```markdown -[WARNING] -======= -This is a warning. - -It can contain multiple paragraphs. -======= -::: -``` diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index 04a30fc52..4eb3fd79f 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -7,7 +7,7 @@ applies: ece: unavailable --- -# Product Availability +# Applies to Using yaml frontmatter pages can explicitly indicate to each deployment targets availability and lifecycle status diff --git a/docs/syntax/code.md b/docs/syntax/code.md index 12cae9623..8c3e2d920 100644 --- a/docs/syntax/code.md +++ b/docs/syntax/code.md @@ -2,7 +2,9 @@ Code blocks can be used to display multiple lines of code. They preserve formatting and provide syntax highlighting when possible. -### Syntax +## Syntax + +Start and end a code block with a code fence. A code fence is a sequence of at least three consecutive backtick characters (~```~). You can optionally add a language identifier to enable syntax highlighting. ````markdown ```yaml @@ -18,45 +20,38 @@ project: github: https://github.com/jupyter-book/mystmd ``` -### Asciidoc syntax +### Code callouts -```markdown -[source,sh] --------------------------------------------------- -GET _tasks -GET _tasks?nodes=nodeId1,nodeId2 -GET _tasks?nodes=nodeId1,nodeId2&actions=cluster:* --------------------------------------------------- -``` +There are two ways to add callouts to a code block. When using callouts, you must use one callout format. You cannot combine explicit and magic callouts. -### Code blocks with callouts +#### Explicit callouts -A code block can include `<\d+>` at the end to indicate code callouts. -A code block with this style of callouts **needs** to be followed by an ordered list with an equal amount of items as called out. -Otherwise, the docs-builder will throw an error. +Add `<\d+>` to the end of a line to explicitly create a code callout. -This syntax mimics what was implemented for our asciidoc system +An ordered list with the same number of items as callouts must follow the code block. If the number of list items doesn’t match the callouts, docs-builder will throw an error. ````markdown ```yaml project: - title: MyST Markdown - github: https://github.com/jupyter-book/mystmd license: - code: MIT content: CC-BY-4.0 <1> - subject: MyST Markdown ``` 1. The license ```` +```yaml +project: + license: + content: CC-BY-4.0 <1> +``` + +1. The license -### Magic Callout -You can include the callouts also directly as code using either `//` or `#` comments. +#### Magic Callouts -These will then be listed and numbered automatically +If a code block contains code comments in the form of `//` or `#`, callouts will be magically created 🪄. ````markdown ```csharp @@ -65,42 +60,38 @@ var client = new ElasticsearchClient("", apiKey); ``` ```` -Will output: - ```csharp var apiKey = new ApiKey(""); // Set up the api key var client = new ElasticsearchClient("", apiKey); ``` -:::{note} -the comments have the follow code to be hoisted as a callout. -::: +Code comments must follow code to be hoisted as a callout. For example: ````markdown ```csharp // THIS IS NOT A CALLOUT -var apiKey = new ApiKey(""); // However this is +var apiKey = new ApiKey(""); // This is a callout var client = new ElasticsearchClient("", apiKey); ``` ```` -will output: - ```csharp // THIS IS NOT A CALLOUT -var apiKey = new ApiKey(""); // However this is +var apiKey = new ApiKey(""); // This is a callout var client = new ElasticsearchClient("", apiKey); ``` -## Console output - -We document alot of API endpoints at Elastic for this you can use `console` as language. The term console relates to the dev console in kibana which users can link to directly from these code snippets. +## Console code blocks :::{note} -We are still actively developing this special block and it's features +This feature is still being developed. ::: +We document a lot of API endpoints at Elastic. For these endpoints, we support `console` as a language. The term console relates to the dev console in kibana which users can link to directly from these code snippets. + +In a console code block, the first line is highlighted as a dev console string and the remainder as json: + ````markdown ```console GET /mydocuments/_search @@ -113,8 +104,6 @@ GET /mydocuments/_search ``` ```` -Will render as: - ```console GET /mydocuments/_search { @@ -124,5 +113,3 @@ GET /mydocuments/_search } } ``` - -The first line is highlighted as a dev console string and the remainder as json. diff --git a/docs/syntax/comments.md b/docs/syntax/comments.md index b26972208..78626700b 100644 --- a/docs/syntax/comments.md +++ b/docs/syntax/comments.md @@ -1,5 +1,7 @@ # Comments +Elastic docs V3 currently only supports single-line comments. + ## Single line comments Use `%` to add single-line comments. @@ -8,8 +10,4 @@ Use `%` to add single-line comments. % This is a comment ``` -Make sure to add a space after the `%`. - -::::{note} -Currently multi-line comments are not supported. -:::: \ No newline at end of file +Make sure to add a space after the `%`. \ No newline at end of file diff --git a/docs/syntax/conditionals.md b/docs/syntax/conditionals.md index da9642e2a..0f9db8123 100644 --- a/docs/syntax/conditionals.md +++ b/docs/syntax/conditionals.md @@ -1,5 +1,5 @@ # Conditionals :::{warning} -This feature is not currently supported in Elastic Docs V3. +This feature will not be supported in Elastic Docs V3. ::: \ No newline at end of file diff --git a/docs/syntax/dropdowns.md b/docs/syntax/dropdowns.md index fe777aaf3..2661a9c47 100644 --- a/docs/syntax/dropdowns.md +++ b/docs/syntax/dropdowns.md @@ -29,25 +29,3 @@ Dropdown content :open: Dropdown content ::: - -## Asciidoc syntax - -```asciidoc -.The `elasticsearch-setup-passwords` tool is deprecated. -[%collapsible] -==== -Details:: -The `elasticsearch-setup-passwords` tool is deprecated in 8.0. To -manually reset the password for built-in users (including the `elastic` user), use -the {ref}/reset-password.html[`elasticsearch-reset-password`] tool, the {es} -{ref}/security-api-change-password.html[change passwords API], or the -User Management features in {kib}. -`elasticsearch-setup-passwords` will be removed in a future release. - -Impact:: -Passwords are generated automatically for the `elastic` user when you start {es} -for the first time. If you run `elasticsearch-setup-passwords` after -starting {es}, it will fail because the `elastic` -user password is already configured. -==== -``` diff --git a/docs/syntax/example_blocks.md b/docs/syntax/example_blocks.md index 1d7e7464d..6470554a5 100644 --- a/docs/syntax/example_blocks.md +++ b/docs/syntax/example_blocks.md @@ -1,5 +1,5 @@ # Example blocks :::{warning} -This feature is not currently supported in Elastic Docs V3. +This feature will not be supported in Elastic Docs V3. ::: \ No newline at end of file diff --git a/docs/syntax/frontmatter.md b/docs/syntax/frontmatter.md index 1405198b7..19c0abaad 100644 --- a/docs/syntax/frontmatter.md +++ b/docs/syntax/frontmatter.md @@ -1,10 +1,10 @@ # Frontmatter -Each MD file referenced in the TOC may optionally define a frontmatter. Frontmatter is YAML-formatted metadata about a page, at the beginning of each file. +Every Markdown file referenced in the TOC may optionally define a frontmatter block. Frontmatter is YAML-formatted metadata about a page, at the beginning of each file. Supported frontmatter includes: | Frontmatter | Learn more | | ------------------- | --------------------------- | -| `navigation_title` | See [title](./titles.md) | -| `applies` | See [product availability](./applies.md) | +| `navigation_title` | See [](./titles.md) | +| `applies` | See [](./applies.md) | diff --git a/docs/syntax/index.md b/docs/syntax/index.md index d3f60f425..e481c8735 100644 --- a/docs/syntax/index.md +++ b/docs/syntax/index.md @@ -1,7 +1,70 @@ # Syntax guide -Elastic docs V3 supports markdown and various directives that add additional functionality to markdown. +Elastic Docs V3 uses [Markdown](https://commonmark.org) as its main content authoring format. -In many cases, plain Markdown syntax will be sufficient when authoring content. +:::{admonition} New to Markdown? +[Learn Markdown in just 10 minutes](https://commonmark.org/help/). +::: -All MD files that are referenced in the TOC require [frontmatter](./frontmatter.md). \ No newline at end of file +V3 fully supports [CommonMark](https://commonmark.org/), a strongly defined, standard-compliant Markdown specification. In many cases, plain Markdown syntax will be sufficient when authoring Elastic content. On top of this functionality, there are two main syntax extension points: + +* [Directives](#directives) +* [GitHub-flavored markdown](#github-flavored-markdown) + +## Directives + +Directives extend CommonMark functionality. Directives have the following syntax: + +```markdown +:::{EXTENSION} ARGUMENTS +:OPTION: VALUE + +Nested content that will be parsed as markdown +::: +``` + +- `EXTENSION` is the name of the directive. Names are always wrapped in brackets `{ }`. For example: [`{note}`](admonitions.md#note). +- `ARGUMENT` an optional main argument. For example: [`:::{include} _snippets/include.md :::`](file_inclusion.md) +- `:OPTION: VALUE` is used to further customize a given directive. + +Defining directives with `:::` allows the nested markdown syntax to be highlighted properly by editors and web viewers. + +### Nesting Directives + +Increase the number of leading semicolons to include nested directives. + +In the following example, a `{note}` wraps a `{hint}`: + +```markdown +::::{note} My note +:::{hint} My hint +Content displayed in the hint admonition +::: +Content displayed in the note admonition +:::: +``` + +## Literal directives + +Many Markdown editors support syntax highlighting for embedded code blocks. For compatibility with this feature, use triple backticks instead of triple colons for content that needs to be displayed literally: + +````markdown +```js +const x = 1; +``` +```` + +## GitHub Flavored Markdown + +We support _some_ [GitHub Flavored Markdown (GFM) extensions](https://github.github.com/gfm/). + +### Supported + +* [](tables.md#github-flavored-markdown-gfm-table) +* Strikethrough: ~~as seen here~~ + +### Not supported + +* Task lists +* Auto links (http://www.elastic.co) +* Using a subset of HTML diff --git a/docs/syntax/md-extensions.md b/docs/syntax/md-extensions.md deleted file mode 100644 index cd64263ab..000000000 --- a/docs/syntax/md-extensions.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title_navigation: Markdown Syntax ---- - -# Markdown Syntax Extensions - -## Syntax - -The new documentation fully supports [CommonMark](https://commonmark.org/) Markdown syntax. - -On top of this widely accepted feature set we have various extensions points. - -## Directives - -Directives are our main extension point over markdown and follows the following syntax - - -```markdown -:::{EXTENSION} ARGUMENTS -:OPTION: VALUE - -Nested content that will be parsed as markdown -::: -``` - -- `EXTENSION` is the name of the directive e.g [`note`](admonitions.md#note) -- `ARGUMENT` some directives take a main argumnt e.g [`:::{include} _snippets/include.md`](file_inclusion.md) -- `OPTION` and `VALUE` can be used to further customize a given directive. - -The usage of `:::` allows the nested markdown to be syntax highlighted properly by editors and web viewers. - -Our (directives) are always wrapped in brackets `{ }`. - -### Nesting Directives - -You can increase the leading semicolons to include nested directives. Here the `{note}` wraps a `{hint}`. - -```markdown -::::{note} My note -:::{hint} My hint -Content displayed in the hint admonition -::: -Content displayed in the note admonition -:::: -``` - -## Literal directives - -For best editor compatability it is recommended to use triple backticks for content that needs to be displayed literally - -````markdown -```js -const x = 1; -``` -```` - -Many markdown editors support syntax highlighting for embedded code blocks. - -## Github Flavored Markdown - -We support some of GitHub flavor markdown extensions these are highlighted in green here: https://github.github.com/gfm/ - -Supported: - -* GFM Tables [](tables.md#github-flavored-markdown-gfm-table) -* Strikethrough ~~as seen here~~ - -Not supported: - -* Task lists -* Auto links (http://www.elastic.co) -* Using a subset of html - diff --git a/docs/syntax/passthrough.md b/docs/syntax/passthrough.md index 64a73cc31..ad9e0e7be 100644 --- a/docs/syntax/passthrough.md +++ b/docs/syntax/passthrough.md @@ -1,5 +1,5 @@ # Passthrough blocks :::{warning} -This feature is not currently supported in Elastic Docs V3. +This feature will not be supported in Elastic Docs V3. ::: \ No newline at end of file diff --git a/docs/syntax/sidebars.md b/docs/syntax/sidebars.md index 9a2500ce4..52e74e418 100644 --- a/docs/syntax/sidebars.md +++ b/docs/syntax/sidebars.md @@ -1,5 +1,5 @@ # Sidebars :::{warning} -This feature is not currently supported in Elastic Docs V3. +This feature will not be supported in Elastic Docs V3. ::: \ No newline at end of file diff --git a/docs/syntax/sundries.md b/docs/syntax/sundries.md index 8c5f417e7..a10ef1487 100644 --- a/docs/syntax/sundries.md +++ b/docs/syntax/sundries.md @@ -1,21 +1,23 @@ # Sundries +A collection of assorted markdown formatting. + ## Inline text formatting Note that there should be no space between the enclosing markers and the text. -**strong**, _emphasis_, `literal text`, \*escaped symbols\* - -~~strikethrough~~ is supported through MyST `strikethrough` extension. +| Syntax | Result | +| ------------------- | --------------------------- | +| \*\*strong\*\* | **strong** | +| \_emphasis\_ | _emphasis_ | +| \`literal text\` |`literal text` | +| \~\~strikethrough\~\~ | ~~strikethrough~~ | +| `\*escaped symbols\*` | \*escaped symbols\* | ## Subscript & Superscript H~2~O, and 4^th^ of July -## Block attributes - -Using Myst's `attrs_block` extension, we can add attributes to a block-level element. For example we can use it to add a class to a header, paragraph, etc. Check out quotation section for another example. - ## Quotation Here is a quote. The attribution is added using the block attribute `attribution`. @@ -23,11 +25,6 @@ Here is a quote. The attribution is added using the block attribute `attribution {attribution="Hamlet act 4, Scene 5"} > We know what we are, but know not what we may be. -## Line breaks - -You can break a paragraph \ -using `\` at the end of a line. - ## Thematic break Same as using `
` HTML tag: diff --git a/docs/syntax/tabs.md b/docs/syntax/tabs.md index 40d6057ac..9dffce62e 100644 --- a/docs/syntax/tabs.md +++ b/docs/syntax/tabs.md @@ -153,53 +153,3 @@ Other content for Golang tab that is not in the same group ::: :::: - -## Asciidoc syntax - -`````asciidoc -**`widget.asciidoc`** - -[source,asciidoc] ----- -++++ -
-
- - -
-
-++++ - -// include::content.asciidoc[tag=central-config] - -++++ -
- -
-++++ ----- - -**`content.asciidoc`** - -[source,asciidoc] ----- -// tag::central-config[] -This is where the content for tab #1 goes. -// end::central-config[] - -// tag::reg-config[] -This is where the content for tab #2 goes. -// end::reg-config[] ----- -``` -````` diff --git a/docs/syntax/tagged_regions.md b/docs/syntax/tagged_regions.md index 8d6acad98..397b5b223 100644 --- a/docs/syntax/tagged_regions.md +++ b/docs/syntax/tagged_regions.md @@ -1,5 +1,5 @@ # Tagged regions ```{warning} -This feature is not currently supported in Elastic Docs V3. See [File inclusion](./file_inclusion.md) for an alternative. +This feature will not be supported in Elastic Docs V3. See [File inclusion](./file_inclusion.md) for an alternative. ``` From ce2ae811ee7edba3def5d77b5a717bbb5d29ef2b Mon Sep 17 00:00:00 2001 From: bmorelli25 Date: Tue, 4 Feb 2025 10:00:48 -0800 Subject: [PATCH 2/4] fix bug; add mv docs --- docs/contribute/move.md | 31 ++++ docs/docset.yml | 1 + docs/migration/guide/automated.md | 253 ------------------------------ 3 files changed, 32 insertions(+), 253 deletions(-) create mode 100644 docs/contribute/move.md diff --git a/docs/contribute/move.md b/docs/contribute/move.md new file mode 100644 index 000000000..fdebd5784 --- /dev/null +++ b/docs/contribute/move.md @@ -0,0 +1,31 @@ +# Move files and folders + +When you move a source file or folder, you must also update all inbound and outbound links to reflect the new file location. `docs-builder` provides tooling to handle this step for you. + +## `docs-builder mv` + +Move a file or folder from one location to another and update all links in the documentation. For example: + +``` +docs-builder mv ./old-location/ia.md ./new-location/ia.md +``` + +:::{important} +The `docset.yml` and `toc.yml` files are not automatically updated when using this tool. You must update these references manually. +::: + +## `docs-builder mv --help` + +``` +Usage: mv [arguments...] [options...] [-h|--help] [--version] + +Move a file or folder from one location to another and update all links in the documentation + +Arguments: + [0] The source file or folder path to move from + [1] The target file or folder path to move to + +Options: + --dry-run Dry run the move operation (Default: null) + -p|--path Defaults to the`{pwd}` folder (Default: null) +``` \ No newline at end of file diff --git a/docs/docset.yml b/docs/docset.yml index ef044b426..f1733f894 100644 --- a/docs/docset.yml +++ b/docs/docset.yml @@ -30,6 +30,7 @@ toc: - file: index.md - file: locally.md - file: on-the-web.md + - file: move.md - folder: migration children: - file: index.md diff --git a/docs/migration/guide/automated.md b/docs/migration/guide/automated.md index 7cf1ce2a5..3525aa6c7 100644 --- a/docs/migration/guide/automated.md +++ b/docs/migration/guide/automated.md @@ -44,256 +44,3 @@ For more information, see [Navigation](../../configure/content-set/navigation.md ## Next steps That’s all you need to get started migrating automated docs to V3. As you add more pages or custom features, refer to the linked resources for details on configuring your docset, refining navigation, and leveraging the full power of V3 directives. - -# Troubleshoot {{elastic-defend}} [ts-management] - - -This topic covers common troubleshooting issues when using {{elastic-defend}}'s [endpoint management tools](../../../solutions/security/manage-elastic-defend.md). - - -## Endpoints [ts-endpoints] - -:::::{dropdown} Unhealthy {{agent}} status -:name: ts-unhealthy-agent - -In some cases, an `Unhealthy` {{agent}} status may be caused by a failure in the {{elastic-defend}} integration policy. In this situation, the integration and any failing features are flagged on the agent details page in {{fleet}}. Expand each section and subsection to display individual responses from the agent. - -::::{tip} -Integration policy response information is also available from the **Endpoints** page in the {{security-app}} (**Manage** → **Endpoints**, then click the link in the **Policy status** column). -:::: - - -:::{image} ../../../images/security-unhealthy-agent-fleet.png -:alt: Agent details page in {{fleet}} with Unhealthy status and integration failures -:class: screenshot -::: - -Common causes of failure in the {{elastic-defend}} integration policy include missing prerequisites or unexpected system configuration. Consult the following topics to resolve a specific error: - -* [Approve the system extension for {{elastic-endpoint}}](../../../solutions/security/configure-elastic-defend/enable-access-for-macos-monterey.md#system-extension-endpoint) (macOS) -* [Enable Full Disk Access for {{elastic-endpoint}}](../../../solutions/security/configure-elastic-defend/enable-access-for-macos-monterey.md#enable-fda-endpoint) (macOS) -* [Resolve a potential system deadlock](../../../troubleshoot/security/elastic-defend.md#linux-deadlock) (Linux) - -::::{tip} -If the {{elastic-defend}} integration policy is not the cause of the `Unhealthy` agent status, refer to [{{fleet}} troubleshooting](../../../troubleshoot/ingest/fleet/common-problems.md) for help with the {{agent}}. -:::: - - -::::: - - -:::::{dropdown} Disabled to avoid potential system deadlock (Linux) -:name: linux-deadlock - -If you have an `Unhealthy` {{agent}} status with the message `Disabled due to potential system deadlock`, that means malware protection was disabled on the {{elastic-defend}} integration policy due to errors while monitoring a Linux host. - -You can resolve the issue by configuring the policy’s [advanced settings](../../../solutions/security/configure-elastic-defend/configure-linux-file-system-monitoring.md) related to **fanotify**, a Linux feature that monitors file system events. By default, {{elastic-defend}} works with fanotify to monitor specific file system types that Elastic has tested for compatibility, and ignores other unknown file system types. - -If your network includes nonstandard, proprietary, or otherwise unrecognized Linux file systems that cause errors while being monitored, you can configure {{elastic-defend}} to ignore those file systems. This allows {{elastic-defend}} to resume monitoring and protecting the hosts on the integration policy. - -::::{warning} -Ignoring file systems can create gaps in your security coverage. Use additional security layers for any file systems ignored by {{elastic-defend}}. -:::: - - -To resolve the potential system deadlock error: - -1. Go to **Manage** → **Policies**, then click a policy’s name. -2. Scroll to the bottom of the policy and click **Show advanced settings**. -3. In the setting `linux.advanced.fanotify.ignored_filesystems`, enter a comma-separated list of file system names to ignore, as they appear in `/proc/filesystems` (for example: `ext4,tmpfs`). Refer to [Find file system names](../../../solutions/security/configure-elastic-defend/configure-linux-file-system-monitoring.md#find-file-system-names) for more on determining the file system names. -4. Click **Save**. - - Once you save the policy, malware protection is re-enabled. - - -::::: - - -:::::{dropdown} Required transform failed -:name: ts-transform-failed - -If you encounter a `“Required transform failed”` notice on the Endpoints page, you can usually resolve the issue by restarting the transform. Refer to [Transforming data](../../../explore-analyze/transforms.md) for more information about transforms. - -:::{image} ../../../images/security-endpoints-transform-failed.png -:alt: Endpoints page with Required transform failed notice -:class: screenshot -::: - -To restart a transform that’s not running: - -1. Go to **Kibana** → **Stack Management** → **Data** → **Transforms**. -2. Enter `endpoint.metadata` in the search box to find the transforms for {{elastic-defend}}. -3. Click the **Actions** menu (**…​**) and do one of the following for each transform, depending on the value in the **Status** column: - - * `stopped`: Select **Start** to restart the transform. - * `failed`: Select **Stop** to first stop the transform, and then select **Start** to restart it. - - :::{image} ../../../images/security-transforms-start.png - :alt: Transforms page with Start option selected - :class: screenshot - ::: - -4. On the confirmation message that displays, click **Start** to restart the transform. -5. The transform’s status changes to `started`. If it doesn’t change, refresh the page. - -::::: - - -:::::{dropdown} {agent} and Endpoint connection issues -:name: ts-agent-connection - -After {{agent}} installs Endpoint, Endpoint connects to {{agent}} over a local relay connection to report its health status and receive policy updates and response action requests. If that connection cannot be established, the {{elastic-defend}} integration will cause {{agent}} to be in an `Unhealthy` status, and Endpoint won’t operate properly. - - -### Identify if the issue is happening [_identify_if_the_issue_is_happening] - -You can identify if this issue is happening in the following ways: - -* Run {{agent}}'s status command: - - * `sudo /opt/Elastic/Agent/elastic-agent status` (Linux) - * `sudo /Library/Elastic/Agent/elastic-agent status` (macOS) - * `c:\Program Files\Elastic\Agent\elastic-agent.exe status` (Windows) - - If the status result for `endpoint-security` says that Endpoint has missed check-ins or `localhost:6788` cannot be bound to, it might indicate this problem is occurring. - -* If the problem starts happening right after installing Endpoint, check the value of `fleet.agent.id` in the following file: - - * `/opt/Elastic/Endpoint/elastic-endpoint.yaml` (Linux) - * `/Library/Elastic/Endpoint/elastic-endpoint.yaml` (macOS) - * `c:\Program Files\Elastic\Endpoint\elastic-endpoint.yaml` (Windows) - - * If the value of `fleet.agent.id` is `00000000-0000-0000-0000-000000000000`, this indicates this problem is occurring. - - ::::{note} - If this problem starts happening after Endpoint has already been installed and working properly, then this value will have changed even though the problem is happening. - :::: - -### Examine Endpoint logs [_examine_endpoint_logs] - -If you’ve confirmed that the issue is happening, you can look at Endpoint log messages to identify the cause: - -* `Failed to find connection to validate. Is Agent listening on 127.0.0.1:6788?` or `Failed to validate connection. Is Agent running as root/admin?` means that Endpoint is not able to create an initial connection to {{agent}} over port `6788`. -* `Unable to make GRPC connection in deadline(60s). Fetching connection info again` means that Endpoint’s original connection to {{agent}} over port `6788` worked, but the connection over port `6789` is failing. - - -### Resolve the issue [_resolve_the_issue] - -To debug and resolve the issue, follow these steps: - -1. Since 8.7.0, Endpoint diagnostics contain a file named `analysis.txt` that contains information about what may cause this issue. As of 8.11.2, {{agent}} diagnostics automatically include Endpoint diagnostics. For previous versions, you can gather Endpoint diagnostics by running: - - * `sudo /opt/Elastic/Endpoint/elastic-endpoint diagnostics` (Linux) - * `sudo /Library/Elastic/Endpoint/elastic-endpoint diagnostics` (macOS) - * `c:\Program Files\Elastic\Endpoint\elastic-endpoint.exe diagnostics` (Windows) - -2. Make sure nothing else on your device is listening on ports `6788` or `6789` by running: - - * `sudo netstat -anp --tcp` (Linux) - * `sudo netstat -an -f inet` (macOS) - * `netstat -an` (Windows) - -3. Make sure `localhost` can be resolved to `127.0.0.1` by running: - - * `ping -4 -c 1 localhost` (Linux) - * `ping -c 1 localhost` (macOS) - * `ping -4 localhost` (Windows) - - -::::: - - -::::{dropdown} {elastic-defend} deployment issues -:name: defend-deployment - -After deploying {{elastic-defend}}, you might encounter warnings or errors in the endpoint’s **Policy status** in {{fleet}} if your mobile device management (MDM) is misconfigured or certain permissions for {{elastic-endpoint}} aren’t granted. The following sections explain issues that can cause warnings or failures in the endpoint’s policy status. - - -### Connect Kernel has failed [_connect_kernel_has_failed] - -This means that the system extension or kernel extension was not approved. Consult the following topics for approving the system extension with or without MDM: - -* [Approve the system extension with MDM](../../../solutions/security/configure-elastic-defend/deploy-on-macos-with-mdm.md#system-extension-jamf) -* [Approve the system extension without MDM](../../../solutions/security/configure-elastic-defend/enable-access-for-macos-monterey.md#system-extension-endpoint) - -You can validate the system extension is loaded by running: - -```shell -sudo systemextensionsctl list | grep co.elastic.systemextension -``` - -In the command output, the system extension should be marked as "active enabled". - - -### Connect Kernel has failed and the system extension is loaded [_connect_kernel_has_failed_and_the_system_extension_is_loaded] - -If the system extension is loaded and kernel connection still fails, this means that Full Disk Access was not granted. {{elastic-endpoint}} requires Full Disk Access to subscribe to system events through the {{elastic-defend}} framework, which is one of the primary sources of eventing information used by {{elastic-endpoint}}. Consult the following topics for granting Full Disk Access with or without MDM: - -* [Enable Full Disk Access with MDM](../../../solutions/security/configure-elastic-defend/deploy-on-macos-with-mdm.md#fda-jamf) -* [Enable Full Disk Access without MDM](../../../solutions/security/configure-elastic-defend/enable-access-for-macos-ventura-higher.md#enable-fda-endpoint-ven) - -You can validate that Full Disk Access is approved by running - -```shell -sudo /Library/Elastic/Endpoint/elastic-endpoint test install -``` - -If the command output doesn’t contain a message about enabling Full Disk Access, the approval was successful. - - -### Detect Network Events has failed [_detect_network_events_has_failed] - -This means that the network extension content filtering was not approved. Consult the following topics for approving network content filtering with or without MDM: - -* [Approve network content filtering with MDM](../../../solutions/security/configure-elastic-defend/deploy-on-macos-with-mdm.md#content-filtering-jamf) -* [Approve network content filtering without MDM](../../../solutions/security/configure-elastic-defend/enable-access-for-macos-ventura-higher.md#allow-filter-content-ven) - -You can validate that network content filtering is approved by running - -```shell -sudo /Library/Elastic/Endpoint/elastic-endpoint test install -``` - -If the command output doesn’t contain a message about approving network content filtering, the approval was successful. - - -### Full Disk Access has a warning [_full_disk_access_has_a_warning] - -This means that Full Disk Access was not granted for one or all {{elastic-endpoint}} components. Consult the following topics for granting Full Disk Access with or without MDM: - -* [Enable Full Disk Access with MDM](../../../solutions/security/configure-elastic-defend/deploy-on-macos-with-mdm.md#fda-jamf) -* [Enable Full Disk Access without MDM](../../../solutions/security/configure-elastic-defend/enable-access-for-macos-ventura-higher.md#enable-fda-endpoint-ven) - -You can validate that Full Disk Access is approved by running - -```shell -sudo /Library/Elastic/Endpoint/elastic-endpoint test install -``` - -If the command output doesn’t contain a message about enabling Full Disk Access, the approval was successful. - -:::: - - -::::{dropdown} Disable {{elastic-defend}}'s self-healing feature on Windows -:name: disable-self-healing - - -### Volume Snapshot Service issues [self-healing-vss-issues] - -{{elastic-defend}}'s self-healing feature rolls back recent filesystem changes when a prevention alert is triggered. This feature uses the Windows Volume Snapshot Service. Although it’s uncommon for this to cause issues, you can turn off this {{elastic-defend}} feature if needed. - -If issues occur and the self-healing feature is enabled, you can turn it off by setting `windows.advanced.alerts.rollback.self_healing.enabled` to `false` in the integration policy advanced settings. Refer to [Configure self-healing rollback for Windows endpoints](../../../solutions/security/configure-elastic-defend/configure-self-healing-rollback-for-windows-endpoints.md) for more information. - -{{elastic-defend}} may also use the Volume Snapshot Service to ensure the feature works properly even when it’s turned off. To opt out of this, set `windows.advanced.diagnostic.rollback_telemetry_enabled` to `false` in the same settings. - - -### Known compatibility issues [self-healing-compatibility-issues] - -There are some known compatibility issues between {{elastic-defend}}'s self-healing feature and filesystem replication features, including [DFS Replication](https://learn.microsoft.com/en-us/windows-server/storage/dfs-replication/dfsr-overview) and Veeam Replication. This may manifest as `DFSR Event ID 1102`: - -`The DFS Replication service has temporarily stopped replication because another application is performing a backup or restore operation. Replication will resume after the backup or restore operation has finished.` - -There are no known workarounds for this issue other than to turn off the self-healing feature. - -:::: \ No newline at end of file From ed2451500cb41751cd6825332f7bf06215ce6549 Mon Sep 17 00:00:00 2001 From: bmorelli25 Date: Tue, 4 Feb 2025 10:04:30 -0800 Subject: [PATCH 3/4] more bugs --- docs/migration/guide/automated.md | 4 ++-- docs/migration/guide/file-structure.md | 7 ------- 2 files changed, 2 insertions(+), 9 deletions(-) delete mode 100644 docs/migration/guide/file-structure.md diff --git a/docs/migration/guide/automated.md b/docs/migration/guide/automated.md index 3525aa6c7..db2b5f057 100644 --- a/docs/migration/guide/automated.md +++ b/docs/migration/guide/automated.md @@ -15,8 +15,8 @@ Once you have these files, follow the [Contribute Locally guide](../../contribut Elastic docs V3 fully supports [CommonMark](https://commonmark.org/) Markdown syntax. In addition, we support: -* Custom directives — our main extension point over markdown (learn more [here](../../syntax/md-extensions.md#directives)) -* A few GitHub flavored markdown extensions (see the list [here](../../syntax/md-extensions.md#github-flavored-markdown)) +* Custom directives — our main extension point over markdown (learn more [here](../../syntax/index.md)) +* A few GitHub flavored markdown extensions (see the list [here](../../syntax/index.md)) In most cases, plain Markdown covers basic needs, and directives add extra functionality as needed. diff --git a/docs/migration/guide/file-structure.md b/docs/migration/guide/file-structure.md deleted file mode 100644 index 7f20f8087..000000000 --- a/docs/migration/guide/file-structure.md +++ /dev/null @@ -1,7 +0,0 @@ -# File structure - -In both the AsciiDoc- and V3-based systems, file structure is largely independent from the resulting site navigation. - -## File and directory structure - -AsciiDoc files and assets (like images and videos) can be stored anywhere within the directories provided as `sources` for a given book in the central [`config.yaml` file in the /docs repo](https://github.com/elastic/docs/blob/master/conf.yaml). From ce50ca3e1f83707f5b60be9a667d736bf1720058 Mon Sep 17 00:00:00 2001 From: bmorelli25 Date: Tue, 4 Feb 2025 10:09:03 -0800 Subject: [PATCH 4/4] last bug --- docs/docset.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/docset.yml b/docs/docset.yml index f1733f894..ecc2e2828 100644 --- a/docs/docset.yml +++ b/docs/docset.yml @@ -18,6 +18,7 @@ external_hosts: - google.com - checkvist.com - commonmark.org + - github.io exclude: - '_*.md' subs: