# Adding external documentation Cortex is your source of truth to external docs. Instead of digging through wikis and other resources, you can aggregate docs on the relevant entities in Cortex in the following ways: * [Adding links to an entity](#add-links-to-an-entity) * [Displaying Swagger, OpenAPI, or AsyncAPI specs on an entity](#documentation-types) * [Embedding git-driven markdown](#git-driven-markdown-docs) * [Embedding dashboard charts](#embedded-dashboards) If you have configured the [Slack integration](/ingesting-data-into-cortex/integrations/slack.md), you can use Slack Bot commands to [list an entity's docs links directly in Slack](#referencing-documentation-links-via-slack). ## View links on an entity Links appear on an entity details page in the **Links & docs** section:

Click "Links & docs" on the left side of an entity page.

## Add links to an entity On entities, you can add links to docs, runbooks, tech specs, dashboards, and more. {% tabs %} {% tab title="Cortex UI" %} Before editing an entity via the UI, make sure that UI editing is enabled under [**Settings > GitOps**](https://app.getcortexapp.com/admin/settings/gitops). 1. In Cortex, navigate to an entity. 2. In the upper right corner of the entity details page, click **Configure entity**. 3. Click **Links** on the left side. 4. Click **+Add**. 5. Configure the link: * **Type**: Select the [type of link](#documentation-types). * To create a new type, enter the type name then click the name in the dropdown. * Learn more about [OpenAPI](#swagger-openapi), [AsyncAPI](#asyncapi-documentation), and [dashboard chart](#embed-dashboards) types below. * **Name**: Enter a name for the link. * **URL**: Enter the URL. * **Description**: Add a description of the link. 6. Click **Add**. {% endtab %} {% tab title="Entity descriptor" %} In the entity descriptor, add a list of `link` objects: ```yaml x-cortex-link: - name: Human Readable Name type: runbook url: https://cortex.io description: Optional Description ``` `name`, `type`, and `url` are required. The value of `type` can be defined based on your organization's preferences. Common examples include dashboard, documentation, healthcheck, logs, metrics, and runbook. See the sections below on this page describing [OpenAPI](#swagger-openapi), [AsyncAPI](#async-api), and [dashboard charts](#embed-dashboards). {% endtab %} {% endtabs %} {% hint style="success" %} You can quickly look up links using the [Cortex Slack Bot](#accessing-docs-links-via-slack). {% endhint %} ### Git-driven markdown docs Cortex automatically embeds markdown files from the `docs` folder of your repo or from the root directory. If Cortex detects relevant files, these docs show up under the **Links & docs** page in an entity's sidebar. Cortex uses the [React markdown library](https://github.com/remarkjs/react-markdown) for rendering the documents. ## Documentation types When [adding links to an entity](#add-links-to-an-entity), Cortex supports embedding OpenAPI or AsyncAPI specs, embedding specs from your repository, adding relative links to a repository that isn't associated with the entity, and embedding charts (from Datadog, Grafana, New Relic, or other sources). You can also create a custom type while [adding a link](#add-links-to-an-entity). Cortex supports displaying Swagger/OpenAPI or AsyncAPI specs for each entity in the **API explorer** on an [entity details page](/ingesting-data-into-cortex/entities-overview/entities/details.md). You can also authorize your API and run queries directly in the API explorer. ### OpenAPI docs You can use your [entity descriptor](/ingesting-data-into-cortex/entities-overview/entities.md#defining-entities-via-yaml-file) file as an OpenAPI spec file. As mentioned in the [documentation on entities](/ingesting-data-into-cortex/entities-overview/entities.md), the entity descriptor file extends the OpenAPI spec, so you can implement the spec directly in this file. You may have existing or external specs you want to display in the API explorer from sources such as Swagger Hub or GitHub Raw URL. Add these to the JSON or YAML spec file under the [`x-cortex-link`](#add-links-to-an-entity) block, with the type `openapi`. #### Embed specs from a git repository If you have specs checked into your git repository, you can embed it by adding it as a relative URL with type `openapi`. For example: ```yaml x-cortex-link: - name: My Spec type: OPENAPI url: ./docs/my-openapi-spec.yaml ``` #### **Relative links in another repo** In addition to providing the ability to link to specs *within* the service repo, Cortex also allows for links that reference other git repositories that aren't necessarily associated with your entity but still within your organization. {% hint style="success" %} Power users can also specify a `branch` parameter between the second and the third colon separated group, in the form `github:org/repo:branch:path/to/file`. If this parameter is omitted, we will use the repository's default branch. {% endhint %}
Relative link YAML examples ```yaml x-cortex-link: - name: My GitHub Spec type: OPENAPI url: github:org/repo:path/to/file ``` ```yaml x-cortex-link: - name: My GitLab Spec type: OPENAPI url: gitlab:namespace/project:path/to/file ``` ```yaml x-cortex-link: - name: My Azure DevOps Spec type: OPENAPI url: azuredevops:project/repository:path/to/file ``` ```yaml x-cortex-link: - name: My Bitbucket Spec type: OPENAPI url: bitbucket:workspace/repo:path/to/file ```
#### Adding OpenAPI via the Cortex API Using your [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities.md#cortex-tag), you can also send your OpenAPI JSON or YAML file to the public [endpoint for managing OpenAPI documentation](/api/readme/docs.md) `/api/v1/catalog/documentation/openapi` for each of your entities. One API doc per entity can be uploaded and it will automatically show up as an `API Doc` entry in the dropdown in the API explorer. The request body is the following, in JSON format. See API Docs for authentication details. | Field | Type | Description | | -------- | ------ | ---------------------------- | | **spec** | string | The json or yaml as a string | {% hint style="success" %} Converting YAML or JSON to string You can use a lightweight utility like jq to take your yaml/json and generate a string that can be used for your request: e.g. `$(cat my_file.yaml | jq -Rsa)` {% endhint %} ### AsyncAPI docs You may have existing or external specs you want to display in the API explorer from sources such as Swagger Hub or GitHub Raw URL. Add these to the JSON or YAML spec file under the [`x-cortex-link`](#add-links-to-an-entity) block, with the type `async_api`. If you have specs checked into your Git repository, you can embed it by adding it as a relative URL with type `async_api`. For example: ```yaml x-cortex-link: - name: My Spec type: ASYNC_API url: ./docs/my-spec.yml ``` ### Embedded dashboards Cortex supports embedding charts from [Datadog](/ingesting-data-into-cortex/integrations/datadog.md), [Grafana](/ingesting-data-into-cortex/integrations/grafana.md), or [New Relic](/ingesting-data-into-cortex/integrations/newrelic.md) directly into an entity for quick access. To view embedded charts, click the **Dashboard** page in the [entity's sidebar](/ingesting-data-into-cortex/entities-overview/entities/details.md#entity-details-sidebar). You can add charts to an entity's YAML: ```yaml x-cortex-dashboards: embeds: - type: datadog | grafana | newrelic (optional) url: https://example.com ``` * The `type` field is an optional enum of three types: `datadog`, `grafana`, or `newrelic`. * The `url` field is the `src` value for the `iframe` embed generated by your dashboard tool. * You must use your tool's embed URL for individual charts. * The URL must be publicly accessible. Or, if you can access the iFrame via VPN, it should be accessible in Cortex while also on the VPN. {% hint style="info" %} Note that you can embed individual charts, not dashboards. If you're using Grafana and seeing errors in your Grafana embeds, make sure your Grafana instance [has embeds enabled](https://grafana.com/docs/grafana/latest/administration/configuration/#allow_embedding). {% endhint %} #### Embed content from other sources It is possible to display content from a source other than Datadog, Grafana, or New Relic. To do this, do not specify an option for the `type` field. The URL you add must be publicly accessible or provide cross-platform authentication for Cortex to view and display the iframe. For example, if the content is accessible via VPN, then you should be able to view it in Cortex while on the VPN. ## Accessing docs links via Slack If you have configured the [Slack integration](/ingesting-data-into-cortex/integrations/slack.md), you can use [Slack Bot](/ingesting-data-into-cortex/integrations/slack.md#cortex-bot) commands to list documentation directly in Slack: * `/slack links ` to list all documentation links for an entity * `/slack links [type] ` to list specific types of documentation links for an entity The `type` corresponds to the type of documentation (e.g., `openapi`, `documentation`, etc.). Replace `` with the [entity's tag or ID](/ingesting-data-into-cortex/entities-overview/entities.md#unique-identifiers-for-entities). For example: * To list all documentation links for an entity with ID `en29f044598b112345`, you could run the following command in Slack:\ `/cortex links en29f044598b112345` * To list the OpenAPI specs for an entity with tag `plugin-extension`, you could run the following command in Slack:\ `/cortex links openapi plugin-extension` {% hint style="info" %} The Slack Bot `links` command works for any docs links listed under `x-cortex-links`. Note that it does not list the [charts](#embedded-dashboards) listed under `x-cortex-dashboards`. {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/external-docs.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.