From 8e444d77f74153cdd29adbe557df4b6c47a587a4 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Tue, 28 Jan 2025 08:22:14 -0800 Subject: [PATCH] Add basic content on what's needed to build docs with docs-builder (#338) * add basic conversion doc * add more updates * add migration tooling docs --- docs/configure/content-set/attributes.md | 24 +++- docs/configure/content-set/file-structure.md | 8 +- docs/configure/content-set/index.md | 16 ++- docs/configure/content-set/navigation.md | 124 ++++++++++++++++++- docs/configure/index.md | 40 +++++- docs/configure/page.md | 10 +- docs/configure/site/content.md | 28 +++-- docs/configure/site/index.md | 39 ++++-- docs/configure/site/landing-page.md | 2 +- docs/configure/site/redirects.md | 4 +- docs/configure/site/shared-attributes.md | 27 ---- docs/docset.yml | 5 +- docs/migration/guide/automated.md | 46 +++++++ docs/migration/guide/bug-bash.md | 58 +++++++++ docs/migration/guide/index.md | 67 +--------- docs/migration/guide/tooling.md | 26 ++++ docs/syntax/frontmatter.md | 1 - docs/syntax/line_breaks.md | 6 + docs/syntax/titles.md | 6 +- 19 files changed, 404 insertions(+), 133 deletions(-) delete mode 100644 docs/configure/site/shared-attributes.md create mode 100644 docs/migration/guide/automated.md create mode 100644 docs/migration/guide/bug-bash.md create mode 100644 docs/migration/guide/tooling.md create mode 100644 docs/syntax/line_breaks.md diff --git a/docs/configure/content-set/attributes.md b/docs/configure/content-set/attributes.md index 0d17f665..cf4344f9 100644 --- a/docs/configure/content-set/attributes.md +++ b/docs/configure/content-set/attributes.md @@ -1,3 +1,25 @@ # Attributes -tbd \ No newline at end of file +To promote consistency across documentation, AsciiDoc uses shared attributes for common terms, URLs, and versions. + +In the AsciiDoctor-based system, shared attributes are defined at the site-level and 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. + +## In `docs-builder` + +Attributes are defined at the content set-level. Use the `subs` key to define attributes as key-value pairs in the content sets `docset.yml` or `toc.yml` file. + +Example: + +```yml +subs: + attr-name: "attr value" + ea: "Elastic Agent" + es: "Elasticsearch" +``` + +## Use attributes + +Attributes can be referenced in documentation file with the following syntax: `{{attr-name-here}}`. diff --git a/docs/configure/content-set/file-structure.md b/docs/configure/content-set/file-structure.md index a7331e3a..d2505c67 100644 --- a/docs/configure/content-set/file-structure.md +++ b/docs/configure/content-set/file-structure.md @@ -1,3 +1,9 @@ # File structure -tbd \ No newline at end of file +The file structure of each content set directly impacts the url path structure of each page. In other words, the directory structure you pull into docs-builder is the same as the directory structure it spits out. + +## Navigation + +Navigation is set independent of directory and file structure in docset and toc files. + +See [Navigation](./navigation.md) to learn more. diff --git a/docs/configure/content-set/index.md b/docs/configure/content-set/index.md index dfecb92b..30586e71 100644 --- a/docs/configure/content-set/index.md +++ b/docs/configure/content-set/index.md @@ -1,12 +1,20 @@ --- -navigation_title: Content set +navigation_title: Content set-level --- -# Content set configuration +# Content set-level configuration -Now we'll zoom into the AsciiDoc book level, and explore the V3 equivalent: content sets. At the book level, the system consists of: +Elastic documentation is spread across multiple repositories. Each repository can contain one or more content sets. A content set is a group of documentation pages whose navigation is defined by a single `docset.yml` file. `docs-builder` builds each content set in isolation, ensuring that changes in one repository don’t affect another. + +A content set in `docs-builder` is equivalent to an AsciiDoc book. At this 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)) | 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)) | `docset.yml` and/or `toc.yml` file(s) | + +## Learn more + +* [File structure](./file-structure.md) +* [Navigation](./navigation.md) +* [Attributes](./attributes.md) \ No newline at end of file diff --git a/docs/configure/content-set/navigation.md b/docs/configure/content-set/navigation.md index 73fc6083..f7094709 100644 --- a/docs/configure/content-set/navigation.md +++ b/docs/configure/content-set/navigation.md @@ -1,3 +1,125 @@ # Navigation -tbd \ No newline at end of file +Two types of nav files are supported: `docset.yml` and `toc.yml`. + +## `docset.yml` + +Example: + +```yaml +project: 'PROJECT_NAME' + +external_hosts: + - EXTERNAL_LINKS_HERE + +exclude: + - 'EXCLUDED_FILES' + +toc: + - file: index.md + - toc: elastic-basics + - folder: top-level-bucket-a + children: + - file: index.md + - file: file-a.md + - file: file-b.md + - folder: top-level-bucket-b + children: + - file: index.md + - folder: second-level-bucket-c + children: + - file: index.md +``` + +### `project` + +The name of the project. + +Example: + +```yaml +project: 'APM Java agent reference' +``` + +### `external_hosts` + +All links to external hosts must be declared in this section of `docset.yml`. + +Example: + +```yaml +external_hosts: + - google.com + - github.com +``` + +### `exclude` + +Files to exclude from the TOC. Supports glob patterns. + +The following example excludes all markdown files beginning with `_`: + +```yaml +exclude: + - '_*.md' +``` + +### `toc` + +Defines the table of contents (navigation) for the content set. A minimal toc is: + +```yaml +toc: + - file: index.md +``` + +The table of contents can be created independent of the directory structure of the files it defines. You can use directories to define nesting in the TOC, but you don't have to. For example, both of the following create the same nav structure: + +```yaml + ... + - file: subsection/index.md + children: + - file: subsection/page-one.md + - file: subsection/page-two.md +``` + +```yaml + ... + - folder: subsection + children: + - file: index.md + - file: page-one.md + - file: page-two.md +``` + +#### Nest `toc` + +The `toc` key can include nested `toc.yml` files. + +The following example includes two sub-`toc.yml` files located in directories named `elastic-basics` and `solutions`: + +```yml +toc: + - file: index.md + - toc: elastic-basics + - toc: solutions +``` + +### Attributes + +Example: + +```yml +subs: + attr-name: "attr value" + ea: "Elastic Agent" + es: "Elasticsearch" +``` + +See [Attributes](./attributes.md) to learn more. + +## `toc.yml` + +As a rule, each `docset.yml` file can only be included once in the assembler. This prevents us from accidentally duplicating pages in the docs. However, there are times when you want to split content sets and include them partially in different areas of the TOC. That's what `toc.yml` files are for. These files split one documentation set into multiple “sub-TOCs,” each mapped to a different navigation node. + +All configuration options that `docset.yml` supports are supported by `toc.yml`. \ No newline at end of file diff --git a/docs/configure/index.md b/docs/configure/index.md index 1e1769d5..bdc318f7 100644 --- a/docs/configure/index.md +++ b/docs/configure/index.md @@ -4,6 +4,40 @@ navigation_title: Configuration reference # Configure Elastic Docs -* [Page configuration](./page.md) -* [Content-set configuration](./content-set/index.md) -* [Site configuration](./site/index.md) \ No newline at end of file +It's first important to understand how we build Elastic Docs: + +| System property | Asciidoc | V3 | +| -------------------- | -------------------- | -------------------- | +| **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)) | + +When working with `docs-builder`, there are three levels at which you can configure Elastic documentation: + +1. Site-level +2. Content set-level +3. Page-level + +## Site-level configuration + +At the site level, you can configure: + +* Content sources: where files live +* Global navigation: how navigations are compiled and presented to users + +[Site configuration](./site/index.md) + +## Content-level configuration + +At the content set level, you can configure: + +* Content-set-level and sub-content-set-level navigation: how smaller groups of files are organized and presented to users +* Attributes: variables that will be substituted at build-time for pre-defined values + +[Content-set configuration](./content-set/index.md) + +## Page-level configuration + +At the page level, you can configure: + +* Frontmatter that influences on-page UX to benefit the user in some way + +[Page configuration](./page.md) \ No newline at end of file diff --git a/docs/configure/page.md b/docs/configure/page.md index cc9ab254..feb3bdb7 100644 --- a/docs/configure/page.md +++ b/docs/configure/page.md @@ -1,11 +1,7 @@ --- -navigation_title: Page +navigation_title: Page-level --- -# Page configuration +# Page-level configuration -tbd - -go into frontmatter here? - -for now, see [frontmatter](../syntax/frontmatter.md). \ No newline at end of file +For now, page configuration is minimal. See [frontmatter](../syntax/frontmatter.md) for supported options. \ No newline at end of file diff --git a/docs/configure/site/content.md b/docs/configure/site/content.md index c0693156..0f335ed8 100644 --- a/docs/configure/site/content.md +++ b/docs/configure/site/content.md @@ -1,8 +1,26 @@ -# Content config +# `assembler.yml` -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. +The global navigation is defined in the `assembler.yml` file. This file can roughly be thought of as the V3 equivalent of conf.yaml in the asciidoc build system. This file, which writers own, allows for arbitrary nesting of `docset.yml` and `toc.yml` references. This file will live in the `elastic/docs-content` repository, but will not build or have any influence over the `docs-builder` builds in that repo. -In the AsciiDoctor system, this all happens in one YAML file in the /docs repo. In the V3 system, this ... +The global navigation that is defined in `assembler.yml` can be composed of three main resources: +1. Local TOC files: toc.yml files that live in the docs-content repository. +2. External TOC files: A subset of a content set (represented by a toc.yml file) that is external to the docs-content repository. +3. External content set declarations: An entire docset.yml file that is external to the docs-content repository. + +The `assembler.yml` file might look something like this: + +```yaml + +``` + +## Assembler constraints + +To maintain each docset’s immutability and self-containment, resources in the global navigation (assembler.yml) must follow specific rules. +1. A link resource can appear only once in the global navigation, and it must nest directly under another resource (not under individual pages from a different content set). In other words: + 1. Each docset.yml or toc.yml file can appear only once in the overall navigation. + 1. Any TOC declarations—whether in docset.yml or toc.yml—must be placed either at the top level or directly under another TOC entry, with no individual files in between. +1. Nested resources must appear either before or after (default) the parent’s TOC, and they cannot be placed arbitrarily among the parent’s pages (e.g., between two files of the parent). +1. If an external TOC is linked, all of its child TOCs must also be included in the global navigation. ## AsciiDoctor conf.yml @@ -35,7 +53,3 @@ In the AsciiDoctor-powered site, content configuration at the site level is done repo: docs path: shared/settings.asciidoc ``` - -## V3 configuration - -TO DO \ No newline at end of file diff --git a/docs/configure/site/index.md b/docs/configure/site/index.md index e60ef44c..2603e797 100644 --- a/docs/configure/site/index.md +++ b/docs/configure/site/index.md @@ -1,25 +1,42 @@ --- -navigation_title: Site +navigation_title: Site-level --- -# Site configuration - -Start by understanding how the new V3 system works at the site level compared to how our custom AsciiDoctor system works. The system consists of: +# Site-level configuration +Start by understanding how the new V3 system works at the site level compared to how our custom AsciiDoctor system works. At the site-level, we have: | System property | Asciidoc | V3 | | -------------------- | -------------------- | -------------------- | | **Content sources** --> 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)) | +| **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 `assembler.yml` | Where these pieces live and what format they are in varies between the two systems, but they generally achieve the same goal. -## Asciidoc +## Content sources -![site-level config in the asciidoc system](./img/site-level-asciidoctor.png) +TBD + +## Content configuration + +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 happens in the `assembler.yml` file in `docs-content`. + +[assembler.yml](./content.md) + +## Landing page -## V3 +See [landing page](./landing-page.md) -DIAGRAM NEEDED \ No newline at end of file +## Redirects + +Plan still needed + +## V3 site-level diagram + +DIAGRAM NEEDED + +## Asciidoc site-level diagram + +![site-level config in the asciidoc system](./img/site-level-asciidoctor.png) diff --git a/docs/configure/site/landing-page.md b/docs/configure/site/landing-page.md index c464f941..b38ab0c5 100644 --- a/docs/configure/site/landing-page.md +++ b/docs/configure/site/landing-page.md @@ -1,3 +1,3 @@ # Landing page -tbd \ No newline at end of file +The landing page will initially be an HTML template. To update the landing page, you will directly edit the HTML template. Eventually, we will templetize the landing page for easier updates. diff --git a/docs/configure/site/redirects.md b/docs/configure/site/redirects.md index 3b16fd16..46d0da0d 100644 --- a/docs/configure/site/redirects.md +++ b/docs/configure/site/redirects.md @@ -18,7 +18,7 @@ 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 +* 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/configure/site/shared-attributes.md b/docs/configure/site/shared-attributes.md deleted file mode 100644 index 0fff17cd..00000000 --- a/docs/configure/site/shared-attributes.md +++ /dev/null @@ -1,27 +0,0 @@ -# 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/docset.yml b/docs/docset.yml index fa1bce39..814e3823 100644 --- a/docs/docset.yml +++ b/docs/docset.yml @@ -43,6 +43,9 @@ toc: - folder: guide children: - file: index.md + - file: automated.md + - file: tooling.md + - file: bug-bash.md - file: file-structure.md - file: mapping.md - folder: configure @@ -52,7 +55,6 @@ toc: children: - file: index.md - file: content.md - - file: shared-attributes.md - file: landing-page.md - file: redirects.md - folder: content-set @@ -75,6 +77,7 @@ toc: - file: file_inclusion.md - file: frontmatter.md - file: images.md + - file: line_breaks.md - file: links.md - file: passthrough.md - file: applies.md diff --git a/docs/migration/guide/automated.md b/docs/migration/guide/automated.md new file mode 100644 index 00000000..be233f3b --- /dev/null +++ b/docs/migration/guide/automated.md @@ -0,0 +1,46 @@ +# Migrate Automated Content to V3 + +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. + +## Minimum Viable Setup + +You can build docs with `docs-builder` using just two files: + +1. **`docset.yml`** — Configures the docset for `docs-builder`. +2. **`index.md`** — A Markdown file that will be converted to HTML. + +Once you have these files, follow the [Contribute Locally guide](../../contribute/locally.md) to get your docs building. + +## Syntax + +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)) + +In most cases, plain Markdown covers basic needs, and directives add extra functionality as needed. + +- At a minimum, each page must have an H1 heading: + ```markdown + # I'm a heading + ``` +- You can optionally include [frontmatter](../../syntax/frontmatter.md) for additional metadata. + +For more details on custom directives, see the [Syntax Guide](../../syntax/index.md). + +## Navigation + +Your `docset.yml` file configures how `docs-builder` handles navigation. Below is a minimal example: + +```yaml +project: 'PROJECT_NAME' + +toc: + - file: index.md +``` + +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 diff --git a/docs/migration/guide/bug-bash.md b/docs/migration/guide/bug-bash.md new file mode 100644 index 00000000..4387475f --- /dev/null +++ b/docs/migration/guide/bug-bash.md @@ -0,0 +1,58 @@ +# 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/index.md b/docs/migration/guide/index.md index a3020082..4bf60cce 100644 --- a/docs/migration/guide/index.md +++ b/docs/migration/guide/index.md @@ -1,66 +1,7 @@ # Migration Guide -How to migrate content from Asciidoc to V3. +Migrate content from Asciidoc to V3 -## Migration tooling - -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. - -After running the migration tool, you can move and manipulate files while viewing a live preview of the content with docs-builder. - -## Building migrated content sets for the bug bash - -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 -``` - -## Pre-migrated content sets available for 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) \ No newline at end of file +* [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 diff --git a/docs/migration/guide/tooling.md b/docs/migration/guide/tooling.md new file mode 100644 index 00000000..3f2cb045 --- /dev/null +++ b/docs/migration/guide/tooling.md @@ -0,0 +1,26 @@ +# Run migration tooling + +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. + + +## 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: + +* Moves files to their new home in the new IA +* Nests content at a pre-selected depth + * shortens directory and file names +* Adds frontmatter mapping files to their asciidoc equivalent + +### File/Dir mappings + +* [`shortened-slugs.js`](https://github.com/elastic/docs-helpers/blob/post-migration-sort/post-migration-sort/input/field-mapping/shortened-slugs.js) +* [`word-replacement.js`](https://github.com/elastic/docs-helpers/blob/post-migration-sort/post-migration-sort/input/field-mapping/word-replacement.js) + +## Post-migration manual work + +* Being tracked in 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 diff --git a/docs/syntax/frontmatter.md b/docs/syntax/frontmatter.md index e0fdae10..1405198b 100644 --- a/docs/syntax/frontmatter.md +++ b/docs/syntax/frontmatter.md @@ -6,6 +6,5 @@ Supported frontmatter includes: | Frontmatter | Learn more | | ------------------- | --------------------------- | -| `title` | See [title](./titles.md) | | `navigation_title` | See [title](./titles.md) | | `applies` | See [product availability](./applies.md) | diff --git a/docs/syntax/line_breaks.md b/docs/syntax/line_breaks.md new file mode 100644 index 00000000..ee5aabda --- /dev/null +++ b/docs/syntax/line_breaks.md @@ -0,0 +1,6 @@ +# Line breaks + +A new line in markdown starts a new paragraph. This is the standard way to separate distinct blocks of text. + +## Forced Line Breaks +If you need to force a line break within a paragraph without starting a new one, you can use `
`. Only `
` is supported; variations like `
` are not supported. \ No newline at end of file diff --git a/docs/syntax/titles.md b/docs/syntax/titles.md index 692f670c..af89fe57 100644 --- a/docs/syntax/titles.md +++ b/docs/syntax/titles.md @@ -14,13 +14,13 @@ Each page is required to at least define a level one heading. This title is used both by the documentation navigation -* Left hand site +* Left hand site * Navigational elements such as breadcrumbs and previous/next links. -As well as when using the autolink naming feature e.g: +As well as when using the [auto text links](./links.md#auto-text-links), e.g: ```markdown -[titles.md]() +[](titles.md) ``` Generated link text: [](titles.md)