Update doc slugs to improve analytic tracking, move to appropriate fo…

…lders (#113630) * Update the slugs to improve google analytics drilldown tracking * more slug updates * Fix some formatting issues in building blocks * update paths Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
elastic · Oct 4, 2021 · eddbc8d · eddbc8d
1 parent a4eab44
commit eddbc8d
Show file tree

Hide file tree

Showing 27 changed files with 220 additions and 219 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,5 +1,5 @@
 # Contributing to Kibana
 
-If you are an employee at Elastic, please check out our Developer Guide [here](https://docs.elastic.dev/kibana-dev-docs/welcome).
+If you are an employee at Elastic, please check out our Developer Guide [here](https://docs.elastic.dev/kibana-dev-docs/getting-started/welcome).
 
 If you are an external developer, we have a legacy developer guide [here](https://www.elastic.co/guide/en/kibana/master/development.html), or you can view the raw docs from our new, internal Developer Guide [here](./dev_docs/getting_started/dev_welcome.mdx). Eventually, our internal Developer Guide will be opened for public consumption.
diff --git a/STYLEGUIDE.mdx b/STYLEGUIDE.mdx
@@ -1,6 +1,6 @@
 ---
 id: kibStyleGuide
-slug: /kibana-dev-docs/styleguide
+slug: /kibana-dev-docs/contributing/styleguide
 title: Style Guide
 summary: JavaScript/TypeScript styleguide.
 date: 2021-05-06

diff --git a/dev_docs/api_welcome.mdx b/dev_docs/api_welcome.mdx
@@ -1,6 +1,6 @@
 ---
 id: kibDevDocsApiWelcome
-slug: /kibana-dev-docs/api-welcome
+slug: /kibana-dev-docs/api-meta/welcome
 title: Welcome
 summary: How to use our automatically generated API documentation
 date: 2021-02-25

diff --git a/dev_docs/best_practices.mdx → dev_docs/contributing/best_practices.mdx b/dev_docs/best_practices.mdx → dev_docs/contributing/best_practices.mdx
@@ -1,6 +1,6 @@
 ---
 id: kibBestPractices
-slug: /kibana-dev-docs/best-practices
+slug: /kibana-dev-docs/contributing/best-practices
 title: Best practices
 summary: Best practices to follow when building a Kibana plugin.
 date: 2021-03-17

diff --git a/dev_docs/dev_principles.mdx → dev_docs/contributing/dev_principles.mdx b/dev_docs/dev_principles.mdx → dev_docs/contributing/dev_principles.mdx
@@ -1,10 +1,10 @@
 ---
 id: kibDevPrinciples
-slug: /kibana-dev-docs/dev-principles
+slug: /kibana-dev-docs/contributing/dev-principles
 title: Developer principles
-summary: Follow our development principles to help keep our code base stable, maintainable and scalable. 
+summary: Follow our development principles to help keep our code base stable, maintainable and scalable.
 date: 2021-03-04
-tags: ['kibana','onboarding', 'dev', 'architecture']
+tags: ['kibana', 'onboarding', 'dev', 'architecture']
 ---
 
 Over time, the Kibana project has been shaped by certain principles. Like Kibana itself, some of these principles were formed by intention while others were the result of evolution and circumstance, but today all are important for the continued success and maintainability of Kibana.
@@ -117,4 +117,4 @@ The primary consumers of the code we write, the APIs that we create, and the fea
 
 Features that we anticipate end users, admins, and plugin developers consuming should be documented through our official docs, but module-level READMEs and code comments are also appropriate.
 
-Documentation is critical part of developing features and code, so an undocumented feature is an incomplete feature.
+Documentation is critical part of developing features and code, so an undocumented feature is an incomplete feature.
diff --git a/dev_docs/contributing/how_we_use_github.mdx b/dev_docs/contributing/how_we_use_github.mdx
@@ -1,6 +1,6 @@
 ---
 id: kibGitHub
-slug: /kibana-dev-docs/github
+slug: /kibana-dev-docs/contributing/github
 title: How we use Github
 summary: Forking, branching, committing and using labels in the Kibana GitHub repo
 date: 2021-09-16

diff --git a/dev_docs/getting_started/add_data.mdx b/dev_docs/getting_started/add_data.mdx
@@ -1,6 +1,6 @@
 ---
 id: kibDevAddData
-slug: /kibana-dev-docs/tutorial/sample-data
+slug: /kibana-dev-docs/getting-started/sample-data
 title: Add data
 summary: Learn how to add data to Kibana
 date: 2021-08-11

diff --git a/dev_docs/getting_started/dev_welcome.mdx b/dev_docs/getting_started/dev_welcome.mdx
@@ -1,6 +1,6 @@
 ---
 id: kibDevDocsWelcome
-slug: /kibana-dev-docs/welcome
+slug: /kibana-dev-docs/getting-started/welcome
 title: Welcome
 summary: Build custom solutions and applications on top of Kibana.
 date: 2021-01-02

diff --git a/dev_docs/getting_started/hello_world_plugin.mdx b/dev_docs/getting_started/hello_world_plugin.mdx
@@ -1,6 +1,6 @@
 ---
 id: kibHelloWorldApp
-slug: /kibana-dev-docs/hello-world-app
+slug: /kibana-dev-docs/getting-started/hello-world-app
 title: Hello World
 summary: Build a very basic plugin that registers an application that says "Hello World!".
 date: 2021-08-03

diff --git a/dev_docs/getting_started/setting_up_a_development_env.mdx b/dev_docs/getting_started/setting_up_a_development_env.mdx
@@ -1,6 +1,6 @@
 ---
 id: kibDevTutorialSetupDevEnv
-slug: /kibana-dev-docs/tutorial/setup-dev-env
+slug: /kibana-dev-docs/getting-started/setup-dev-env
 title: Set up a Development Environment
 summary: Learn how to setup a development environment for contributing to the Kibana repository
 date: 2021-04-26

diff --git a/dev_docs/troubleshooting.mdx → dev_docs/getting_started/troubleshooting.mdx b/dev_docs/troubleshooting.mdx → dev_docs/getting_started/troubleshooting.mdx
@@ -1,6 +1,6 @@
 ---
 id: kibTroubleshooting
-slug: /kibana-dev-docs/troubleshooting
+slug: /kibana-dev-docs/getting-started/troubleshooting
 title: Troubleshooting
 summary: A collection of tips for working around strange issues.
 date: 2021-09-08

diff --git a/dev_docs/key_concepts/anatomy_of_a_plugin.mdx b/dev_docs/key_concepts/anatomy_of_a_plugin.mdx
@@ -1,6 +1,6 @@
 ---
 id: kibDevAnatomyOfAPlugin
-slug: /kibana-dev-docs/anatomy-of-a-plugin
+slug: /kibana-dev-docs/key-concepts/anatomy-of-a-plugin
 title: Anatomy of a plugin
 summary: Anatomy of a Kibana plugin.
 date: 2021-08-03

diff --git a/dev_docs/building_blocks.mdx → dev_docs/key_concepts/building_blocks.mdx b/dev_docs/building_blocks.mdx → dev_docs/key_concepts/building_blocks.mdx
@@ -1,26 +1,28 @@
 ---
 id: kibBuildingBlocks
-slug: /kibana-dev-docs/building-blocks
+slug: /kibana-dev-docs/key-concepts/building-blocks
 title: Building blocks
 summary: Consider these building blocks when developing your plugin.
 date: 2021-02-24
-tags: ['kibana','onboarding', 'dev', 'architecture']
+tags: ['kibana', 'onboarding', 'dev', 'architecture']
 ---
 
-When building a plugin in Kibana, there are a handful of architectural "building blocks" you can use. Some of these building blocks are "higher-level", 
-and some are "lower-level". High-level building blocks come 
+When building a plugin in Kibana, there are a handful of architectural "building blocks" you can use. Some of these building blocks are "higher-level",
+and some are "lower-level". High-level building blocks come
 with many built-in capabilities, require less maintenance, and evolve new feature sets over time with little to no
- impact on consumers. When developers use high-level building blocks, new features are exposed consistently, across all of Kibana, at the same time.
-  On the downside, they are not as flexible as our low-level building blocks. 
-
- Low-level building blocks
- provide greater flexibility, but require more code to stitch them together into a meaningful UX. This results in higher maintenance cost for consumers and greater UI/UX variability
- across Kibana.
-
- For example, if an application is using <DocLink id="kibBuildingBlocks" section="index-patterns" text="Index Patterns"/> and 
- <DocLink id="kibBuildingBlocks" section="search-source" text="Search Source"/>, 
- their application would automatically support runtime fields. If the app is instead using the
- lower-level <DocLink id="kibBuildingBlocks" section="search-strategy" text="Search Strategy"/>, additional work would be required.
+impact on consumers. When developers use high-level building blocks, new features are exposed consistently, across all of Kibana, at the same time.
+On the downside, they are not as flexible as our low-level building blocks.
+
+Low-level building blocks
+provide greater flexibility, but require more code to stitch them together into a meaningful UX. This results in higher maintenance cost for consumers and greater UI/UX variability
+across Kibana.
+
+For example, if an application is using <DocLink id="kibBuildingBlocks" section="index-patterns" text="Index Patterns"/> and <DocLink id="kibBuildingBlocks" section="search-source" text="Search Source" />, their application would
+automatically support runtime fields. If the app is instead using the lower-level <DocLink
+  id="kibBuildingBlocks"
+  section="search-strategy"
+  text="Search Strategy"
+/>, additional work would be required.
 
 Armed with this knowledge, you can choose what works best for your use case!
 
@@ -32,35 +34,23 @@ The following high-level building blocks can be rendered directly into your appl
 
 ### Query Bar
 
-The <DocLink id="kibDataPlugin" text="Data plugin"/> provides a high-level Query Bar component that comes with support for Lucene, KQL, Saved Queries, 
-and <DocLink id="kibBuildingBlocks" section="index-patterns" text="Index Patterns"/>.
-
-If you would like to expose the ability to search and filter on Elasticsearch data, the Query Bar provided by the
-<DocLink id="kibDataPlugin" text="Data plugin"/> 
- is your go-to building block.
+The <DocLink id="kibDataPlugin" text="Data plugin"/> provides a high-level Query Bar component that comes with support for Lucene, KQL, Saved Queries,
+and <DocLink id="kibBuildingBlocks" section="index-patterns" text="Index Patterns"/>. If you would like to expose the ability to search and filter on Elasticsearch data, the Query Bar provided by the <DocLink id="kibDataPlugin" text="Data plugin" /> is your go-to building block.
 
 **Github labels**: `Team:AppServices`, `Feature:QueryBar`
 
 ### Dashboard Embeddable
 
 Add a Dashboard Embeddable directly inside your application to provide users with a set of visualizations and graphs that work seamlessly
-with the <DocLink id="kibBuildingBlocks" section="query-bar" text="Query Bar"/>. Every feature that is added to a registered 
-<DocLink id="kibBuildingBlocks" section="embeddables" text="Embeddable"/> 
-(Lens, Maps, Saved Searches and more) will be available automatically, as well as any
- <DocLink id="kibBuildingBlocks" section="ui-actions--triggers" text="UI Actions"/> that are
- added to the Embeddable context menu panel (for example, drilldowns, custom panel time ranges, and "share to" features).
+with the <DocLink id="kibBuildingBlocks" section="query-bar" text="Query Bar"/>. Every feature that is added to a registered <DocLink id="kibBuildingBlocks" section="embeddables" text="Embeddable" /> (Lens, Maps, Saved Searches and more) will be available automatically, as well as any <DocLink id="kibBuildingBlocks" section="ui-actions--triggers" text="UI Actions" /> that are added to the Embeddable context menu panel (for example, drilldowns, custom panel time ranges, and "share to" features).
 
 The Dashboard Embeddable is one of the highest-level UI components you can add to your application.
 
 **Github labels**: `Team:Presentation`, `Feature:Dashboard`
 
 ### Lens Embeddable
 
-Check out the Lens Embeddable if you wish to show users visualizations based on Elasticsearch data without worrying about query building and chart rendering. It's built on top of the
- <DocLink id="kibBuildingBlocks" section="expressions" text="Expression language"/>, and integrates with
-  <DocLink id="kibBuildingBlocks" section="index-patterns" text="Index Patterns"/>
- and <DocLink id="kibBuildingBlocks" section="ui-actions--triggers" text="UI Actions"/>. Using the same configuration, it's also possible to link to
- a prefilled Lens editor, allowing the user to drill deeper and explore their data.
+Check out the Lens Embeddable if you wish to show users visualizations based on Elasticsearch data without worrying about query building and chart rendering. It's built on top of the <DocLink id="kibBuildingBlocks" section="expressions" text="Expression language" />, and integrates with <DocLink id="kibBuildingBlocks" section="index-patterns" text="Index Patterns" /> and <DocLink id="kibBuildingBlocks" section="ui-actions--triggers" text="UI Actions" />. Using the same configuration, it's also possible to link to a prefilled Lens editor, allowing the user to drill deeper and explore their data.
 
 **Github labels**: `Team:VisEditors`, `Feature:Lens`
 
@@ -72,7 +62,7 @@ Check out the Map Embeddable if you wish to embed a map in your application.
 
 ### KibanaPageTemplate
 
-All Kibana pages should use KibanaPageTemplate to setup their pages. It's a thin wrapper around [EuiPageTemplate](https://elastic.github.io/eui/#/layout/page) that makes setting up common types of Kibana pages quicker and easier while also adhering to any Kibana-specific requirements. 
+All Kibana pages should use KibanaPageTemplate to setup their pages. It's a thin wrapper around [EuiPageTemplate](https://elastic.github.io/eui/#/layout/page) that makes setting up common types of Kibana pages quicker and easier while also adhering to any Kibana-specific requirements.
 
 Check out <DocLink id="kibDevDocsKPTTutorial" text="the KibanaPageTemplate tutorial" /> for more implementation guidance.
 
@@ -82,54 +72,60 @@ Check out <DocLink id="kibDevDocsKPTTutorial" text="the KibanaPageTemplate tutor
 
 ### Index Patterns
 
-<DocLink id="kibDataPlugin" section="index-patterns-api" text="Index Patterns"/> are a high-level, space-aware abstraction layer that sits 
-above Data Streams and Elasticsearch indices. Index Patterns provide users the 
-ability to define and customize the data they wish to search and filter on, on a per-space basis. For example, users can specify a set of indices, 
-and they can customize the field list with runtime fields, formatting options and custom labels.
+<DocLink id="kibDataPlugin" section="index-patterns-api" text="Index Patterns" /> are a high-level, space-aware
+abstraction layer that sits above Data Streams and Elasticsearch indices. Index Patterns provide users
+the ability to define and customize the data they wish to search and filter on, on a per-space basis.
+For example, users can specify a set of indices, and they can customize the field list with runtime fields,
+formatting options and custom labels.
 
 Index Patterns are used in many other high-level building blocks so we highly recommend you consider this building block for your search needs.
 
 **Github labels**: `Team:AppServices`, `Feature:Index Patterns`
 
 ### Search Source
 
-<DocLink id="kibDataPlugin" section="searchsource" text="Search Source"/> is a high-level search service offered by the
-<DocLink id="kibDataPlugin" section="searchsource" text="Data plugin"/>. It requires an
-<DocLink id="kibBuildingBlocks" section="index-patterns" text="Index Pattern"/>, and abstracts away the raw ES DSL and search endpoint. Internally
-it uses the ES <DocLink id="kibBuildingBlocks" section="search-strategies" text="Search Strategy"/>. Use Search Source if you need to query data 
-from Elasticsearch, and you aren't already using one of the high-level UI Components that handles this internally.
+<DocLink id="kibDataPlugin" section="searchsource" text="Search Source" /> is a high-level search service
+offered by the <DocLink id="kibDataPlugin" section="searchsource" text="Data plugin" />. It requires
+an <DocLink id="kibBuildingBlocks" section="index-patterns" text="Index Pattern" />, and abstracts away
+the raw ES DSL and search endpoint. Internally it uses the ES <DocLink
+  id="kibBuildingBlocks"
+  section="search-strategies"
+  text="Search Strategy"
+/>
+. Use Search Source if you need to query data from Elasticsearch, and you aren't already using one of
+the high-level UI Components that handles this internally.
 
 **Github labels**: `Team:AppServices`, `Feature:Search`
 
 ### Search Strategies
 
-Search Strategies are a low-level building block that abstracts away search details, like what REST endpoint is being called. The ES Search Strategy 
-is a very lightweight abstraction layer that sits just above querying ES with the elasticsearch-js client. Other search stragies are offered for other 
+Search Strategies are a low-level building block that abstracts away search details, like what REST endpoint is being called. The ES Search Strategy
+is a very lightweight abstraction layer that sits just above querying ES with the elasticsearch-js client. Other search stragies are offered for other
 languages, like EQL and SQL. These are very low-level building blocks so expect a lot of glue work to make these work with the higher-level abstractions.
 
 **Github labels**: `Team:AppServices`, `Feature:Search`
 
 ### Expressions
 
 Expressions are a low-level building block that can be used if you have advanced search needs that requiring piping results into additional functionality, like
-joining and manipulating data. Lens and Canvas are built on top of Expressions. Most developers should be able to use
- <DocLink id="kibBuildingBlocks" section="lens-embeddable" text="Lens"/> or
-  <DocLink id="kibBuildingBlocks" section="search-source" text="Search Source"/>, rather than need to access the Expression language directly.  
+joining and manipulating data. Lens and Canvas are built on top of Expressions. Most developers should be able to use <DocLink id="kibBuildingBlocks" section="lens-embeddable" text="Lens" /> or <DocLink id="kibBuildingBlocks" section="search-source" text="Search Source" />, rather than need to
+access the Expression language directly.{' '}
 
 **Github labels**: `Team:AppServices`, `Feature:ExpressionLanguage`
 
 ## Saved Objects
 
-<DocLink id="kibDevDocsSavedObjectsIntro" text="Saved Objects" /> should be used if you need to persist application-level information. If you were building a TODO
-application, each TODO item would be a `Saved Object`. Saved objects come pre-wired with support for bulk export/import, security features like space sharing and
-space isolation, and tags.
+<DocLink id="kibDevDocsSavedObjectsIntro" text="Saved Objects" /> should be used if you need to persist
+application-level information. If you were building a TODO application, each TODO item would be a `Saved
+Object`. Saved objects come pre-wired with support for bulk export/import, security features like space
+sharing and space isolation, and tags.
 
 **Github labels**: `Team:Core`, `Feature:Saved Objects`
 
 # Integration building blocks
 
 Use the following building blocks to create an inter-connected, cross-application, holistic Kibana experience. These building blocks allow you to expose functionality
- that promotes your own application into other applications, as well as help developers of other applications integrate into your app.
+that promotes your own application into other applications, as well as help developers of other applications integrate into your app.
 
 ## UI Actions & Triggers
 
@@ -141,6 +137,6 @@ application could register a UI Action called "View in Maps" to appear any time
 ## Embeddables
 
 Embeddables help you integrate your application with the Dashboard application. Register your custom UI Widget as an Embeddable and users will
-be able to add it as a panel on a Dashboard. With a little extra work, it can also be exposed in Canvas workpads. 
+be able to add it as a panel on a Dashboard. With a little extra work, it can also be exposed in Canvas workpads.
 
 **Github labels**: `Team:AppServices`, `Feature:Embeddables`
diff --git a/dev_docs/key_concepts/data_views.mdx b/dev_docs/key_concepts/data_views.mdx
@@ -1,16 +1,16 @@
 ---
 id: kibDataViewsKeyConcepts
-slug: /kibana-dev-docs/data-view-intro
+slug: /kibana-dev-docs/key-concepts/data-view-intro
 title: Data Views
 summary: Data views are the central method of defining queryable data sets in Kibana
 date: 2021-08-11
-tags: ['kibana','dev', 'contributor', 'api docs']
+tags: ['kibana', 'dev', 'contributor', 'api docs']
 ---
 
-*Note: Kibana index patterns are currently being renamed to data views. There will be some naming inconsistencies until the transition is complete.*
+_Note: Kibana index patterns are currently being renamed to data views. There will be some naming inconsistencies until the transition is complete._
 
 Data views (formerly Kibana index patterns or KIPs) are the central method of describing sets of indices for queries. Usage is strongly recommended
-as a number of high level <DocLink id="kibBuildingBlocks" text="building blocks"/> rely on them. Further, they provide a consistent view of data across 
+as a number of high level <DocLink id="kibBuildingBlocks" text="building blocks"/> rely on them. Further, they provide a consistent view of data across
 a variety Kibana apps.
 
 Data views are defined by a wildcard string (an index pattern) which matches indices, data streams, and index aliases, optionally specify a
@@ -20,13 +20,10 @@ on the data view via runtime fields. Schema-on-read functionality is provided by
 
 ![image](../assets/data_view_diagram.png)
 
-
-
 The data view API is made available via the data plugin (`data.indexPatterns`, soon to be renamed) and most commonly used with <DocLink id="kibDevTutorialDataSearchAndSessions" section="high-level-search" text="SearchSource" />
 (`data.search.search.SearchSource`) to perform queries. SearchSource will apply existing filters and queries from the search bar UI.
 
 Users can create data views via [Data view management](https://www.elastic.co/guide/en/kibana/current/index-patterns.html).
 Additionally, they can be created through the data view API.
 
 Data views also allow formatters and custom labels to be defined for fields.
-
diff --git a/dev_docs/kibana_platform_plugin_intro.mdx → ...concepts/kibana_platform_plugin_intro.mdx b/dev_docs/kibana_platform_plugin_intro.mdx → ...concepts/kibana_platform_plugin_intro.mdx
@@ -1,6 +1,6 @@
 ---
 id: kibPlatformIntro
-slug: /kibana-dev-docs/platform-intro
+slug: /kibana-dev-docs/key-concepts/platform-intro
 title: Plugins and the Kibana platform
 summary: An introduction to the Kibana platform and how to use it to build a plugin.
 date: 2021-01-06