From ebd1e7a160f4ae11bca9ca46c416bc90318f7678 Mon Sep 17 00:00:00 2001 From: bmorelli25 Date: Mon, 6 Jan 2025 13:42:41 -0800 Subject: [PATCH 1/9] more docs updates --- docs/source/contribute/index.md | 13 +++++++++++ docs/source/docset.yml | 4 ++++ docs/source/migration/index.md | 12 +++++++++++ docs/source/syntax/tables.md | 38 --------------------------------- 4 files changed, 29 insertions(+), 38 deletions(-) create mode 100644 docs/source/contribute/index.md create mode 100644 docs/source/migration/index.md diff --git a/docs/source/contribute/index.md b/docs/source/contribute/index.md new file mode 100644 index 000000000..912d4d3bb --- /dev/null +++ b/docs/source/contribute/index.md @@ -0,0 +1,13 @@ +--- +title: Contribution guide +--- + +Want to contribute to the Elastic documentation? You're in the right spot! + +1. Install dependencies +2. Clone repositories +3. Make changes +4. Open a Pull Request +5. Work with CI +6. Get approvals and merge +7. View your changes live on elastic.co \ No newline at end of file diff --git a/docs/source/docset.yml b/docs/source/docset.yml index 040842bf4..cca9ffe15 100644 --- a/docs/source/docset.yml +++ b/docs/source/docset.yml @@ -19,6 +19,10 @@ exclude: - '_*.md' toc: - file: index.md + - folder: migration + - file: index.md + - folder: contribute + - file: index.md - folder: syntax children: - file: index.md diff --git a/docs/source/migration/index.md b/docs/source/migration/index.md new file mode 100644 index 000000000..428fbac63 --- /dev/null +++ b/docs/source/migration/index.md @@ -0,0 +1,12 @@ +--- +title: Migration guide +--- + +How to migrate content from Asciidoc to V3. + +1. Clone https://github.com/elastic/adoc-to-md +2. Run the migration tool +3. Copy the output to the appropriate directory in https://github.com/elastic/docs-content +4. Update the `docset.yml` file to reflect the new IA of the content set +5. Build your changes with https://github.com/elastic/docs-builder +6. Open a PR and merge your changes \ No newline at end of file diff --git a/docs/source/syntax/tables.md b/docs/source/syntax/tables.md index 0d10e1176..ba8c6a7ac 100644 --- a/docs/source/syntax/tables.md +++ b/docs/source/syntax/tables.md @@ -29,41 +29,3 @@ You can use the GFM table syntax to create a table: | ------- | --------------- | | USA | Washington D.C. | | Canada | Ottawa | - -% Neither of these work -% ## `{table}` Directive -% -% You can use the `table` directive which gives you configuration captions such as caption and alignment. -% -% ```{table} Countries and their capitals -% :widths: auto -% :align: right -% -% | Country | Capital | -% | ------- | --------------- | -% | USA | Washington D.C. | -% | Canada | Ottawa | -% ``` --> -% -% Collections of markup files containing doc content. These are split up across many docs repos. | _Books_ | _Content sets_ | +| **Content configuration** --> A way to specify where to find those content sources, and in what order they should be added to the site. | Configuration file ([`conf.yml`](https://github.com/elastic/docs/blob/master/conf.yaml) in elastic/docs) | Config file location TBD | +| **Cross-site values** --> Key-value pairs that should be substituted across all sources as web pages are built. | Shared attributes ([`shared/`](https://github.com/elastic/docs/tree/master/shared) in elastic/docs) | Shared attrs file TBD | +| **Docs build tool** --> An engine used to take the markup in the content sources and transform it into web pages. | Customized version of AsciiDoctor (lives in [**elastic/docs**](https://github.com/elastic/docs)) | Customized doc builder using open source tools (lives in [**elastic/docs-builder**](https://github.com/elastic/docs-builder)) | + +## Asciidoc + +![site-level config in the asciidoc system](./img/site-level-asciidoctor.png) \ No newline at end of file diff --git a/docs/source/contribute/change-browser.md b/docs/source/contribute/change-browser.md new file mode 100644 index 000000000..106b0cb3d --- /dev/null +++ b/docs/source/contribute/change-browser.md @@ -0,0 +1,11 @@ +--- +title: Update the docs locally +--- + +1. Install dependencies +2. Clone repositories +3. Make changes +4. Open a Pull Request +5. Work with CI +6. Get approvals and merge +7. View your changes live on elastic.co \ No newline at end of file diff --git a/docs/source/contribute/change-local.md b/docs/source/contribute/change-local.md new file mode 100644 index 000000000..d1ab75c13 --- /dev/null +++ b/docs/source/contribute/change-local.md @@ -0,0 +1,3 @@ +--- +title: Update the docs in your web browser +--- diff --git a/docs/source/contribute/index.md b/docs/source/contribute/index.md index 102a4f3d4..345042a7f 100644 --- a/docs/source/contribute/index.md +++ b/docs/source/contribute/index.md @@ -3,12 +3,8 @@ title: Elastic Docs contribution guide navigation_title: Contribution guide --- -Want to contribute to the Elastic documentation? You're in the right spot! +Want to contribute to the Elastic documentation? You're in the right spot! Select an option below to get started: -1. Install dependencies -2. Clone repositories -3. Make changes -4. Open a Pull Request -5. Work with CI -6. Get approvals and merge -7. View your changes live on elastic.co \ No newline at end of file +* I just want to suggest a change --> [Open a docs issue](https://github.com/elastic/docs-content/issues/new?template=internal-request.yaml) +* I want to make a small change to a single page --> [Update the docs in your _web browser_](change-browser.md). +* I want to make a larger change or a change to multiple pages --> [Update the docs in your _code editor_](change-local.md). diff --git a/docs/source/docset.yml b/docs/source/docset.yml index 64f875e31..eeea6ab68 100644 --- a/docs/source/docset.yml +++ b/docs/source/docset.yml @@ -22,9 +22,17 @@ toc: - folder: migration children: - file: index.md + - file: file-structure.md - folder: contribute children: - file: index.md + - file: change-browser.md + - file: change-local.md + - folder: configure + children: + - file: index.md + - file: page-level.md + - file: site-level.md - folder: syntax children: - file: index.md diff --git a/docs/source/migration/file-structure.md b/docs/source/migration/file-structure.md new file mode 100644 index 000000000..675ffeabb --- /dev/null +++ b/docs/source/migration/file-structure.md @@ -0,0 +1,61 @@ +--- +title: 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). + +## 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 From 75f2fff8226323cc53017d3963c66ac40ffe2956 Mon Sep 17 00:00:00 2001 From: bmorelli25 Date: Mon, 6 Jan 2025 16:18:13 -0800 Subject: [PATCH 7/9] add more content --- .../configure/content-set/attributes.md | 5 ++ .../configure/content-set/file-structure.md | 5 ++ docs/source/configure/content-set/index.md | 11 +++++ .../configure/content-set/navigation.md | 5 ++ docs/source/configure/page-level.md | 4 -- docs/source/configure/page.md | 10 ++++ docs/source/configure/site/content.md | 43 ++++++++++++++++++ .../{ => site}/img/site-level-asciidoctor.png | Bin .../{site-level.md => site/index.md} | 8 +++- docs/source/configure/site/landing-page.md | 5 ++ docs/source/configure/site/redirects.md | 26 +++++++++++ .../configure/site/shared-attributes.md | 29 ++++++++++++ docs/source/docset.yml | 16 ++++++- 13 files changed, 160 insertions(+), 7 deletions(-) create mode 100644 docs/source/configure/content-set/attributes.md create mode 100644 docs/source/configure/content-set/file-structure.md create mode 100644 docs/source/configure/content-set/index.md create mode 100644 docs/source/configure/content-set/navigation.md delete mode 100644 docs/source/configure/page-level.md create mode 100644 docs/source/configure/page.md create mode 100644 docs/source/configure/site/content.md rename docs/source/configure/{ => site}/img/site-level-asciidoctor.png (100%) rename docs/source/configure/{site-level.md => site/index.md} (89%) create mode 100644 docs/source/configure/site/landing-page.md create mode 100644 docs/source/configure/site/redirects.md create mode 100644 docs/source/configure/site/shared-attributes.md diff --git a/docs/source/configure/content-set/attributes.md b/docs/source/configure/content-set/attributes.md new file mode 100644 index 000000000..f348d59e2 --- /dev/null +++ b/docs/source/configure/content-set/attributes.md @@ -0,0 +1,5 @@ +--- +title: Attributes +--- + +tbd \ No newline at end of file diff --git a/docs/source/configure/content-set/file-structure.md b/docs/source/configure/content-set/file-structure.md new file mode 100644 index 000000000..a04f108bd --- /dev/null +++ b/docs/source/configure/content-set/file-structure.md @@ -0,0 +1,5 @@ +--- +title: File structure +--- + +tbd \ No newline at end of file diff --git a/docs/source/configure/content-set/index.md b/docs/source/configure/content-set/index.md new file mode 100644 index 000000000..f18cc6c1f --- /dev/null +++ b/docs/source/configure/content-set/index.md @@ -0,0 +1,11 @@ +--- +title: Content set configuration +navigation_title: Content set +--- + +Now we'll zoom into the AsciiDoc book level, and explore the V3 equivalent: content sets. At the book level, the system consists of: + +| System property | Asciidoc | V3 | +| -------------------- | -------------------- | -------------------- | +| **Content source files** --> A whole bunch of markup files as well as any other assets used in the docs (for example, images, videos, and diagrams). | **Markup**: AsciiDoc files **Assets**: Images, videos, and diagrams | **Markup**: MD files **Assets**: Images, videos, and diagrams | +| **Information architecture** --> A way to specify the order in which these text-based files should appear in the information architecture of the book. | `index.asciidoc` file (this can be spread across several AsciiDoc files, but generally starts with the index file specified in the [`conf.yaml` file](https://docs.elastic.dev/migration/site-level/content#asciidoctor-conf-yml)) | TBD | diff --git a/docs/source/configure/content-set/navigation.md b/docs/source/configure/content-set/navigation.md new file mode 100644 index 000000000..9253fa13f --- /dev/null +++ b/docs/source/configure/content-set/navigation.md @@ -0,0 +1,5 @@ +--- +title: Navigation +--- + +tbd \ No newline at end of file diff --git a/docs/source/configure/page-level.md b/docs/source/configure/page-level.md deleted file mode 100644 index e2b17ec9b..000000000 --- a/docs/source/configure/page-level.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Page configuration -navigation_title: Page ---- \ No newline at end of file diff --git a/docs/source/configure/page.md b/docs/source/configure/page.md new file mode 100644 index 000000000..21a35ea9c --- /dev/null +++ b/docs/source/configure/page.md @@ -0,0 +1,10 @@ +--- +title: Page configuration +navigation_title: Page +--- + +tbd + +go into frontmatter here? + +for now, see [frontmatter](../syntax/frontmatter.md). \ No newline at end of file diff --git a/docs/source/configure/site/content.md b/docs/source/configure/site/content.md new file mode 100644 index 000000000..0b96f049a --- /dev/null +++ b/docs/source/configure/site/content.md @@ -0,0 +1,43 @@ +--- +title: Content config +--- + +In both the AsciiDoctor- and V3-based system, there is site-wide configuration where you list all content sources, where to find those sources, and in what order they should be added to the site. + +In the AsciiDoctor system, this all happens in one YAML file in the /docs repo. In the V3 system, this ... + +## AsciiDoctor conf.yml + +In the AsciiDoctor-powered site, content configuration at the site level is done in the [`conf.yaml`](https://github.com/elastic/docs/blob/master/conf.yaml) file in the elastic/docs repo. In the `conf.yml` file, the configuration information for all books are listed in this one file. Here's the example of what it looks like to configure a single book: + +```yaml +- title: Machine Learning + prefix: en/machine-learning + current: *stackcurrent + index: docs/en/stack/ml/index.asciidoc + branches: [ {main: master}, 8.9, 8.8, 8.7, 8.6, 8.5, 8.4, 8.3, 8.2, 8.1, 8.0, 7.17, 7.16, 7.15, 7.14, 7.13, 7.12, 7.11, 7.10, 7.9, 7.8, 7.7, 7.6, 7.5, 7.4, 7.3, 7.2, 7.1, 7.0, 6.8, 6.7, 6.6, 6.5, 6.4, 6.3 ] + live: *stacklive + chunk: 1 + tags: Elastic Stack/Machine Learning + subject: Machine Learning + sources: + - + repo: stack-docs + path: docs/en/stack + - + repo: elasticsearch + path: docs + - + repo: docs + path: shared/versions/stack/{version}.asciidoc + - + repo: docs + path: shared/attributes.asciidoc + - + repo: docs + path: shared/settings.asciidoc +``` + +## V3 configuration + +TO DO \ No newline at end of file diff --git a/docs/source/configure/img/site-level-asciidoctor.png b/docs/source/configure/site/img/site-level-asciidoctor.png similarity index 100% rename from docs/source/configure/img/site-level-asciidoctor.png rename to docs/source/configure/site/img/site-level-asciidoctor.png diff --git a/docs/source/configure/site-level.md b/docs/source/configure/site/index.md similarity index 89% rename from docs/source/configure/site-level.md rename to docs/source/configure/site/index.md index 1d6485678..ecdf1260b 100644 --- a/docs/source/configure/site-level.md +++ b/docs/source/configure/site/index.md @@ -13,6 +13,12 @@ Start by understanding how the new V3 system works at the site level compared to | **Cross-site values** --> Key-value pairs that should be substituted across all sources as web pages are built. | Shared attributes ([`shared/`](https://github.com/elastic/docs/tree/master/shared) in elastic/docs) | Shared attrs file TBD | | **Docs build tool** --> An engine used to take the markup in the content sources and transform it into web pages. | Customized version of AsciiDoctor (lives in [**elastic/docs**](https://github.com/elastic/docs)) | Customized doc builder using open source tools (lives in [**elastic/docs-builder**](https://github.com/elastic/docs-builder)) | +Where these pieces live and what format they are in varies between the two systems, but they generally achieve the same goal. + ## Asciidoc -![site-level config in the asciidoc system](./img/site-level-asciidoctor.png) \ No newline at end of file +![site-level config in the asciidoc system](./img/site-level-asciidoctor.png) + +## V3 + +DIAGRAM NEEDED \ No newline at end of file diff --git a/docs/source/configure/site/landing-page.md b/docs/source/configure/site/landing-page.md new file mode 100644 index 000000000..cff57fdee --- /dev/null +++ b/docs/source/configure/site/landing-page.md @@ -0,0 +1,5 @@ +--- +title: Landing page +--- + +tbd \ No newline at end of file diff --git a/docs/source/configure/site/redirects.md b/docs/source/configure/site/redirects.md new file mode 100644 index 000000000..eca65cf51 --- /dev/null +++ b/docs/source/configure/site/redirects.md @@ -0,0 +1,26 @@ +--- +title: Redirects +--- + +## From an elastic.co/guide page + +The web team owns redirects for `elastic.co`. Writers do not have direct access to the system where www.elastic.co redirects are managed. + +### Permanent redirect + +Currently the only way to implement true redirects from a page on `elastic.co/guide` is to open an issue with the web team, add your request to a Google Sheet, and wait for the web team to address your request. + +### Stopgap + +Writers have developed a stopgap to communicate to users that content has been removed or moved to another location. We create a page at the existing URL that links to the new location of the information. This is better than removing a page without redirecting at all, but is not the best user experience and doesn't align with SEO best practices. + +## From an elastic.co/docs page + +STRATEGY TBD + +## Migration redirects + +Docs inventory script: https://github.com/elastic/docs-helpers/tree/main/docs-inventory +Docs inventory sheet: https://docs.google.com/spreadsheets/d/1LfPI3TZqdpONGxOmL8B8V-Feo1flLwObz9_ibCEMkIQ/edit?gid=605983744#gid=605983744 + +This sheet will be used to request redirects after migration from 8.current to 9.current. \ No newline at end of file diff --git a/docs/source/configure/site/shared-attributes.md b/docs/source/configure/site/shared-attributes.md new file mode 100644 index 000000000..f76ba8721 --- /dev/null +++ b/docs/source/configure/site/shared-attributes.md @@ -0,0 +1,29 @@ +--- +title: Shared attributes +--- + +To promote consistency across documentation, AsciiDoc uses shared attributes for common terms, URLs, and versions. + +In the AsciiDoctor-based system, shared attributes live in the [`shared/` directory](https://github.com/elastic/docs/blob/master/shared) in the elastic/docs repo. The most used files in this directory are: + +The [`attributes.asciidoc` file](https://github.com/elastic/docs/blob/master/shared/attributes.asciidoc), which contains URLs, common words and phrases, and more. +The files in the [`versions/stack` directory](https://github.com/elastic/docs/tree/master/shared/versions/stack), which contain the latest versions for various products for a given Stack version. + +## Versions + +### Asciidoc + +File: [`shared/versions/stack/8.8.asciidoc`](https://github.com/elastic/docs/blob/master/shared/versions/stack/8.8.asciidoc) in the elastic/docs repo + +### V3 + +See [Product availability](../../syntax/applies.md). + + +## URLS + +File: [`shared/attributes.asciidoc`](https://github.com/elastic/docs/blob/master/shared/attributes.asciidoc) in the elastic/docs repo + +## Common terms + +File: [`shared/attributes.asciidoc`](https://github.com/elastic/docs/blob/master/shared/attributes.asciidoc) in the elastic/docs repo \ No newline at end of file diff --git a/docs/source/docset.yml b/docs/source/docset.yml index eeea6ab68..2ca536995 100644 --- a/docs/source/docset.yml +++ b/docs/source/docset.yml @@ -31,8 +31,20 @@ toc: - folder: configure children: - file: index.md - - file: page-level.md - - file: site-level.md + - folder: site + children: + - file: index.md + - file: content.md + - file: shared-attributes.md + - file: landing-page.md + - file: redirects.md + - folder: content-set + children: + - file: index.md + - file: file-structure.md + - file: attributes.md + - file: navigation.md + - file: page.md - folder: syntax children: - file: index.md From 5f5d23db8a3f45d1b9acf083dedf3e0843876b12 Mon Sep 17 00:00:00 2001 From: bmorelli25 Date: Mon, 6 Jan 2025 16:23:45 -0800 Subject: [PATCH 8/9] fix bug? --- docs/source/configure/content-set/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/configure/content-set/index.md b/docs/source/configure/content-set/index.md index f18cc6c1f..69dfdfabe 100644 --- a/docs/source/configure/content-set/index.md +++ b/docs/source/configure/content-set/index.md @@ -8,4 +8,4 @@ Now we'll zoom into the AsciiDoc book level, and explore the V3 equivalent: cont | System property | Asciidoc | V3 | | -------------------- | -------------------- | -------------------- | | **Content source files** --> A whole bunch of markup files as well as any other assets used in the docs (for example, images, videos, and diagrams). | **Markup**: AsciiDoc files **Assets**: Images, videos, and diagrams | **Markup**: MD files **Assets**: Images, videos, and diagrams | -| **Information architecture** --> A way to specify the order in which these text-based files should appear in the information architecture of the book. | `index.asciidoc` file (this can be spread across several AsciiDoc files, but generally starts with the index file specified in the [`conf.yaml` file](https://docs.elastic.dev/migration/site-level/content#asciidoctor-conf-yml)) | TBD | +| **Information architecture** --> A way to specify the order in which these text-based files should appear in the information architecture of the book. | `index.asciidoc` file (this can be spread across several AsciiDoc files, but generally starts with the index file specified in the [`conf.yaml` file](https://docs.elastic.dev/migration/site-level/content)) | TBD | From ceb422f279431bc0a0e0391c6047efd59c1dfc3d Mon Sep 17 00:00:00 2001 From: bmorelli25 Date: Mon, 6 Jan 2025 16:25:59 -0800 Subject: [PATCH 9/9] remove link --- docs/source/configure/content-set/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/configure/content-set/index.md b/docs/source/configure/content-set/index.md index 69dfdfabe..a76e717d9 100644 --- a/docs/source/configure/content-set/index.md +++ b/docs/source/configure/content-set/index.md @@ -8,4 +8,4 @@ Now we'll zoom into the AsciiDoc book level, and explore the V3 equivalent: cont | System property | Asciidoc | V3 | | -------------------- | -------------------- | -------------------- | | **Content source files** --> A whole bunch of markup files as well as any other assets used in the docs (for example, images, videos, and diagrams). | **Markup**: AsciiDoc files **Assets**: Images, videos, and diagrams | **Markup**: MD files **Assets**: Images, videos, and diagrams | -| **Information architecture** --> A way to specify the order in which these text-based files should appear in the information architecture of the book. | `index.asciidoc` file (this can be spread across several AsciiDoc files, but generally starts with the index file specified in the [`conf.yaml` file](https://docs.elastic.dev/migration/site-level/content)) | TBD | +| **Information architecture** --> A way to specify the order in which these text-based files should appear in the information architecture of the book. | `index.asciidoc` file (this can be spread across several AsciiDoc files, but generally starts with the index file specified in the `conf.yaml` file)) | TBD |