From 6d471eb26db65cd8b5985f9bff606781b774ae59 Mon Sep 17 00:00:00 2001 From: kodster28 Date: Thu, 13 Mar 2025 13:30:46 -0500 Subject: [PATCH] Added curl / apirequest to curl examples --- .../guidelines-for-curl-commands.mdx | 11 +++ .../components/directory-listing.mdx | 8 +- .../style-guide/components/github-code.mdx | 6 +- .../style-guide/components/last-reviewed.mdx | 6 +- .../style-guide/components/list-tutorials.mdx | 6 +- .../style-guide/components/public-stats.mdx | 12 ++- .../3rd-party-integration-guide.mdx | 6 +- .../content-types/changelog.mdx | 6 +- .../content-types/concept.mdx | 6 +- .../content-types/configuration.mdx | 48 ++++++------ .../content-types/design-guide.mdx | 8 +- .../content-types/faq.mdx | 6 +- .../content-types/get-started.mdx | 8 +- .../content-types/how-to.mdx | 48 ++++++------ .../content-types/implementation-guide.mdx | 12 ++- .../content-types/navigation.mdx | 16 ++-- .../content-types/overview.mdx | 14 +++- .../reference-architecture-diagram.mdx | 19 ++++- .../content-types/reference-architecture.mdx | 27 +++++-- .../content-types/reference.mdx | 22 +++--- .../content-types/support-content.mdx | 77 ------------------- .../content-types/troubleshooting.mdx | 6 +- .../content-types/tutorial.mdx | 22 ++++-- .../directory-listing-definition.mdx | 5 ++ .../style-guide/public-stats-definition.mdx | 5 ++ src/schemas/base.ts | 25 +++--- 26 files changed, 247 insertions(+), 188 deletions(-) delete mode 100644 src/content/docs/style-guide/documentation-content-strategy/content-types/support-content.mdx create mode 100644 src/content/partials/style-guide/directory-listing-definition.mdx create mode 100644 src/content/partials/style-guide/public-stats-definition.mdx diff --git a/src/content/docs/style-guide/api-content-strategy/guidelines-for-curl-commands.mdx b/src/content/docs/style-guide/api-content-strategy/guidelines-for-curl-commands.mdx index 1f6cb2b69f8ceec..130ff9d756526aa 100644 --- a/src/content/docs/style-guide/api-content-strategy/guidelines-for-curl-commands.mdx +++ b/src/content/docs/style-guide/api-content-strategy/guidelines-for-curl-commands.mdx @@ -6,6 +6,17 @@ sidebar: --- +We follow several formatting conventions for cURL commands. + +## Components + +To automatically incorporate our conventions into your examples, use: + +- [`APIRequest`](/style-guide/components/api-request/): For examples hitting endpoints in the Cloudflare API schema. +- [`CURL`](/style-guide/components/curl/): For other cURL commands. + +## Paramter names + Use long parameter names for clarity: * `--header` (instead of `-H`) diff --git a/src/content/docs/style-guide/components/directory-listing.mdx b/src/content/docs/style-guide/components/directory-listing.mdx index e69e4644b3a2a83..4cae4b1b23caa8d 100644 --- a/src/content/docs/style-guide/components/directory-listing.mdx +++ b/src/content/docs/style-guide/components/directory-listing.mdx @@ -4,7 +4,9 @@ styleGuide: component: DirectoryListing --- -Use `` to display the directory of a specific folder, which appears as a list of links. +import { Render } from "~/components"; + + We also have an optional `descriptions` parameter which - if present - adds in the text from the [front matter `description`](/style-guide/frontmatter/) field. @@ -13,3 +15,7 @@ import { DirectoryListing } from "~/components"; ``` + +## Associated content types + +- [Navigation](/style-guide/documentation-content-strategy/content-types/navigation/) \ No newline at end of file diff --git a/src/content/docs/style-guide/components/github-code.mdx b/src/content/docs/style-guide/components/github-code.mdx index 2a2c73eb952619c..9a61c1a95946e80 100644 --- a/src/content/docs/style-guide/components/github-code.mdx +++ b/src/content/docs/style-guide/components/github-code.mdx @@ -142,4 +142,8 @@ This should be represented as starting `` and closin **type**: `object` -Props to pass to the [Expressive Code component](https://expressive-code.com/key-features/code-component/). \ No newline at end of file +Props to pass to the [Expressive Code component](https://expressive-code.com/key-features/code-component/). + +## Associated content types + +- [Tutorial](/style-guide/documentation-content-strategy/content-types/tutorial/) \ No newline at end of file diff --git a/src/content/docs/style-guide/components/last-reviewed.mdx b/src/content/docs/style-guide/components/last-reviewed.mdx index cd10dd179b428d6..81abd3c3eea0d34 100644 --- a/src/content/docs/style-guide/components/last-reviewed.mdx +++ b/src/content/docs/style-guide/components/last-reviewed.mdx @@ -23,4 +23,8 @@ import { LastReviewed } from "~/components" title: My Tutorial updated: 2024-07-01 --- -``` \ No newline at end of file +``` + +## Associated content types + +- [Tutorial](/style-guide/documentation-content-strategy/content-types/tutorial/) \ No newline at end of file diff --git a/src/content/docs/style-guide/components/list-tutorials.mdx b/src/content/docs/style-guide/components/list-tutorials.mdx index 3378eafc0fff900..d366beb49baafce 100644 --- a/src/content/docs/style-guide/components/list-tutorials.mdx +++ b/src/content/docs/style-guide/components/list-tutorials.mdx @@ -8,4 +8,8 @@ styleGuide: import { ListTutorials } from "~/components"; -``` \ No newline at end of file +``` + +## Associated content types + +- [Tutorial](/style-guide/documentation-content-strategy/content-types/tutorial/) \ No newline at end of file diff --git a/src/content/docs/style-guide/components/public-stats.mdx b/src/content/docs/style-guide/components/public-stats.mdx index 3d5d2fa0b24f0bb..d86c83872fc4222 100644 --- a/src/content/docs/style-guide/components/public-stats.mdx +++ b/src/content/docs/style-guide/components/public-stats.mdx @@ -4,7 +4,9 @@ styleGuide: component: PublicStats --- -The `PublicStats` component allows you to reference specific values about Cloudflare's network without maintaining those values in multiple files. +import { Render } from "~/components"; + + Refer to the examples below for more information. @@ -23,3 +25,11 @@ Cloudflare also has . If you need more stats or to update these stats, submit a pull request to update [PublicStats.astro](https://github.com/cloudflare/cloudflare-docs/blob/production/src/components/PublicStats.astro) ::: + +## Associated content types + +The `PublicStats` component is commonly used on the following type of pages: + +- [Overview](/style-guide/documentation-content-strategy/content-types/overview/) +- [Reference Architecture](/style-guide/documentation-content-strategy/content-types/reference-architecture/) +- [Reference Architecture Diagrams](/style-guide/documentation-content-strategy/content-types/reference-architecture-diagram/) \ No newline at end of file diff --git a/src/content/docs/style-guide/documentation-content-strategy/content-types/3rd-party-integration-guide.mdx b/src/content/docs/style-guide/documentation-content-strategy/content-types/3rd-party-integration-guide.mdx index dcc19cd924adb27..05cd2e741c26d68 100644 --- a/src/content/docs/style-guide/documentation-content-strategy/content-types/3rd-party-integration-guide.mdx +++ b/src/content/docs/style-guide/documentation-content-strategy/content-types/3rd-party-integration-guide.mdx @@ -13,7 +13,11 @@ instructional, straightforward ## content_type -`integration-guide` +```yaml +pcx_content_type: integration-guide +``` + +For more details, refer to [`pcx_content_type`](/style-guide/frontmatter/custom-properties/#pcx_content_type). ## Structure diff --git a/src/content/docs/style-guide/documentation-content-strategy/content-types/changelog.mdx b/src/content/docs/style-guide/documentation-content-strategy/content-types/changelog.mdx index 2086baf7e2c0587..b306fc1bb6c9dd5 100644 --- a/src/content/docs/style-guide/documentation-content-strategy/content-types/changelog.mdx +++ b/src/content/docs/style-guide/documentation-content-strategy/content-types/changelog.mdx @@ -13,7 +13,11 @@ instructional, straightforward ## content_type -`changelog` +```yaml +pcx_content_type: changelog +``` + +For more details, refer to [`pcx_content_type`](/style-guide/frontmatter/custom-properties/#pcx_content_type). ## Ownership diff --git a/src/content/docs/style-guide/documentation-content-strategy/content-types/concept.mdx b/src/content/docs/style-guide/documentation-content-strategy/content-types/concept.mdx index b9fb73cc9d6f54c..f5d019fdccd23f8 100644 --- a/src/content/docs/style-guide/documentation-content-strategy/content-types/concept.mdx +++ b/src/content/docs/style-guide/documentation-content-strategy/content-types/concept.mdx @@ -13,7 +13,11 @@ instructional, descriptive, approachable, supportive ## content_type -`concept` +```yaml +pcx_content_type: concept +``` + +For more details, refer to [`pcx_content_type`](/style-guide/frontmatter/custom-properties/#pcx_content_type). ## Structure diff --git a/src/content/docs/style-guide/documentation-content-strategy/content-types/configuration.mdx b/src/content/docs/style-guide/documentation-content-strategy/content-types/configuration.mdx index 81f5a3358cb1c43..afe963544973687 100644 --- a/src/content/docs/style-guide/documentation-content-strategy/content-types/configuration.mdx +++ b/src/content/docs/style-guide/documentation-content-strategy/content-types/configuration.mdx @@ -14,7 +14,11 @@ plain, descriptive, straightforward ## content\_type -`configuration` +```yaml +pcx_content_type: configuration +``` + +For more details, refer to [`pcx_content_type`](/style-guide/frontmatter/custom-properties/#pcx_content_type). ## When to use @@ -39,46 +43,46 @@ Configurations are useful for parts of the product that are very configuration-i ``` --- -weight: xx +weight: xx pcx_content_type: configuration --- # Title - + Write an overview of the high-level feature here, not more than 2-3 sentences. Outline what users can achieve with it, and if necessary, link to other parts of the docs. - + * [Feature 1](/feature-1) * [Feature 2](/feature-2) * [Feature 3](/feature-3) - + ## Feature 1 - + (Feature 1) allows you to (placeholder). For example, the following configuration (placeholder). - + | Setting 1 | Setting 2 | Setting 3 | - -| - | - | - | - + +| - | - | - | + | Value 1 | Value 2 | Value 3 | - + ## Feature 2 - + (Feature 2) allows you to (placeholder). For example, the following configuration (placeholder). - + | Setting 1 | Setting 2 | Setting 3 | - -| - | - | - | - + +| - | - | - | + | Value 1 | Value 2 | Value 3 | - + ## Feature 3 - + (Feature 3) allows you to (placeholder). For example, the following configuration (placeholder). - + | Setting 1 | Setting 2 | Setting 3 | - -| - | - | - | - + +| - | - | - | + | Value 1 | Value 2 | Value 3 | ``` diff --git a/src/content/docs/style-guide/documentation-content-strategy/content-types/design-guide.mdx b/src/content/docs/style-guide/documentation-content-strategy/content-types/design-guide.mdx index 8e488f83d883038..a56ecb50a908596 100644 --- a/src/content/docs/style-guide/documentation-content-strategy/content-types/design-guide.mdx +++ b/src/content/docs/style-guide/documentation-content-strategy/content-types/design-guide.mdx @@ -14,7 +14,11 @@ instructional, straightforward ## content\_type -`design-guide` +```yaml +pcx_content_type: design-guide +``` + +For more details, refer to [`pcx_content_type`](/style-guide/frontmatter/custom-properties/#pcx_content_type). ## Examples @@ -57,7 +61,7 @@ meta: # Design guide title ## Introduction -Provide context to what this guide is going to cover. Ensure you describe the end state of the solution this guide will detail. +Provide context to what this guide is going to cover. Ensure you describe the end state of the solution this guide will detail. ### Who is this for? This reference architecture is designed for IT or security professionals with some responsibility over or familiarity with their organization’s existing infrastructure. It is useful to have some experience with technologies important to securing hybrid work, including identity providers (IdPs), user directories, single sign on (SSO), endpoint security or management (EPP, XDR, UEM, MDM), firewalls, routers, and point solutions like packet or content inspection hardware, threat prevention, and data loss prevention technologies. diff --git a/src/content/docs/style-guide/documentation-content-strategy/content-types/faq.mdx b/src/content/docs/style-guide/documentation-content-strategy/content-types/faq.mdx index 745f8830366e823..a3f32fa4762652d 100644 --- a/src/content/docs/style-guide/documentation-content-strategy/content-types/faq.mdx +++ b/src/content/docs/style-guide/documentation-content-strategy/content-types/faq.mdx @@ -13,7 +13,11 @@ Guiding, straightforward, educational, authoritative ## content_type -`faq` +```yaml +pcx_content_type: faq +``` + +For more details, refer to [`pcx_content_type`](/style-guide/frontmatter/custom-properties/#pcx_content_type). ## Overview diff --git a/src/content/docs/style-guide/documentation-content-strategy/content-types/get-started.mdx b/src/content/docs/style-guide/documentation-content-strategy/content-types/get-started.mdx index fd106a563ff16ea..2d609d477ca7c01 100644 --- a/src/content/docs/style-guide/documentation-content-strategy/content-types/get-started.mdx +++ b/src/content/docs/style-guide/documentation-content-strategy/content-types/get-started.mdx @@ -1,6 +1,6 @@ --- pcx_content_type: concept -title: Get started page template +title: Get started --- @@ -10,7 +10,11 @@ The purpose of Get started content is to help users go from not using a product ## content\_type -`get-started` +```yaml +pcx_content_type: get-started +``` + +For more details, refer to [`pcx_content_type`](/style-guide/frontmatter/custom-properties/#pcx_content_type). ## Structure diff --git a/src/content/docs/style-guide/documentation-content-strategy/content-types/how-to.mdx b/src/content/docs/style-guide/documentation-content-strategy/content-types/how-to.mdx index 16b04191b2e36e9..30fbed25bf4e34a 100644 --- a/src/content/docs/style-guide/documentation-content-strategy/content-types/how-to.mdx +++ b/src/content/docs/style-guide/documentation-content-strategy/content-types/how-to.mdx @@ -18,7 +18,11 @@ instructional, straightforward ## content\_type -`how-to` +```yaml +pcx_content_type: how-to +``` + +For more details, refer to [`pcx_content_type`](/style-guide/frontmatter/custom-properties/#pcx_content_type). ## Structure @@ -60,11 +64,11 @@ Single procedure how-to weight: xx pcx_content_type: how-to --- - + # Second-person imperative verb phrase - + Context for procedure (optional) - + 1. Step one 1. Step two 1. Step three @@ -81,22 +85,22 @@ How-to with multiple procedures weight: xx pcx_content_type: how-to --- - + # Second-person imperative verb phrase - + Context for procedures on page (optional) - + ## Second-person imperative verb phrase - + 1. Step one 1. Step two 1. Step three 1. ... - + Next steps sentence - what users should see as the end result and/or actionable next steps. - + ## Second-person imperative verb phrase - + 1. Step one 1. Step two 1. Step three @@ -113,35 +117,35 @@ How-to with multiple procedures that must be completed in order weight: xx pcx_content_type: how-to --- - + # Second-person imperative verb phrase - + Context for procedures on page (optional) - + ## 1. Second-person imperative verb phrase - + 1. Step one 1. Step two 1. Step three 1. ... - + Next steps sentence - what users should see as the end result and/or actionable next steps. - + ## 2. Second-person imperative verb phrase - + 1. Step one 1. Step two 1. Step three 1. ... - + Next steps sentence - what users should see as the end result and/or actionable next steps. - + ## 3. Second-person imperative verb phrase - + 1. Step one 1. Step two 1. Step three 1. ... - + Next steps sentence - what users should see as the end result and/or actionable next steps. ``` diff --git a/src/content/docs/style-guide/documentation-content-strategy/content-types/implementation-guide.mdx b/src/content/docs/style-guide/documentation-content-strategy/content-types/implementation-guide.mdx index 0ec5c47afc0f0c8..36c33425a078bdb 100644 --- a/src/content/docs/style-guide/documentation-content-strategy/content-types/implementation-guide.mdx +++ b/src/content/docs/style-guide/documentation-content-strategy/content-types/implementation-guide.mdx @@ -13,11 +13,15 @@ instructional, straightforward ## content\_type -`implementation-guide` +```yaml +pcx_content_type: implementation-guide +``` -## Structure +For more details, refer to [`pcx_content_type`](/style-guide/frontmatter/custom-properties/#pcx_content_type). -### Required components +## Components + +### Required [**Title**](/style-guide/documentation-content-strategy/component-attributes/titles/): Short verb phrase in second-person imperative. Do not use gerund phrases. @@ -25,7 +29,7 @@ instructional, straightforward [**Next steps**](/style-guide/documentation-content-strategy/component-attributes/next-steps/): What users should see as the end result of the steps and/or actionable next steps. -### Optional components +### Optional [**Prerequisites**](/style-guide/documentation-content-strategy/component-attributes/prerequisites/): Tasks or conditions that must be completed before a user can complete a series of steps. diff --git a/src/content/docs/style-guide/documentation-content-strategy/content-types/navigation.mdx b/src/content/docs/style-guide/documentation-content-strategy/content-types/navigation.mdx index 718ae098a732fca..4f8318eeff9511c 100644 --- a/src/content/docs/style-guide/documentation-content-strategy/content-types/navigation.mdx +++ b/src/content/docs/style-guide/documentation-content-strategy/content-types/navigation.mdx @@ -4,19 +4,23 @@ pcx_content_type: concept --- +import { Render } from "~/components"; + ## Purpose The purpose of a navigation page is to direct users deeper into the doc set and act as a sub-landing page for a specific area of the docs. ## content_type -`navigation` +```yaml +pcx_content_type: navigation +``` -## Structure +For more details, refer to [`pcx_content_type`](/style-guide/frontmatter/custom-properties/#pcx_content_type). -Use the `{{}}` component +## Components -**Title**: Verb or noun phrase that describes the sub-pages in the section. +[`DirectoryListing`](/style-guide/components/directory-listing/): ## Template @@ -27,9 +31,9 @@ pcx_content_type: navigation --- import { DirectoryListing } from "~/components" - + # Name of section - + ``` diff --git a/src/content/docs/style-guide/documentation-content-strategy/content-types/overview.mdx b/src/content/docs/style-guide/documentation-content-strategy/content-types/overview.mdx index cd6768da0400531..c556e6ab0e6865e 100644 --- a/src/content/docs/style-guide/documentation-content-strategy/content-types/overview.mdx +++ b/src/content/docs/style-guide/documentation-content-strategy/content-types/overview.mdx @@ -4,6 +4,8 @@ title: Overview --- +import { Render } from "~/components"; + ## Purpose The purpose of a landing page is to welcome users and provide an overview of the product. @@ -14,10 +16,18 @@ Accessible, welcoming, conversational, outspoken ## content\_type -`overview` +```yaml +pcx_content_type: overview +``` + +For more details, refer to [`pcx_content_type`](/style-guide/frontmatter/custom-properties/#pcx_content_type). ## Structure +### Most used components + +- [`PublicStats`](/style-guide/components/public-stats/): + ### Required components **Metadata title**: Overview @@ -99,7 +109,7 @@ Description of external resource related to current product. ## Additional Information -Overview pages are the default "first" page in any nested navigation. In some cases, to ensure good information architecture and navigability, you may need to rename or remove overview pages. +Overview pages are the default "first" page in any nested navigation. In some cases, to ensure good information architecture and navigability, you may need to rename or remove overview pages. ### When to consider removing an verview page diff --git a/src/content/docs/style-guide/documentation-content-strategy/content-types/reference-architecture-diagram.mdx b/src/content/docs/style-guide/documentation-content-strategy/content-types/reference-architecture-diagram.mdx index 50567e893b39df6..9b36229ca99e870 100644 --- a/src/content/docs/style-guide/documentation-content-strategy/content-types/reference-architecture-diagram.mdx +++ b/src/content/docs/style-guide/documentation-content-strategy/content-types/reference-architecture-diagram.mdx @@ -4,6 +4,8 @@ title: Reference architecture diagram --- +import { Render } from "~/components"; + ## Purpose To provide a visual reference and explanation of using Cloudflare for a specific solution. @@ -14,17 +16,26 @@ instructional, straightforward ## content\_type -`reference-architecture-diagram` +```yaml +pcx_content_type: reference-architecture-diagram +``` + +For more details, refer to [`pcx_content_type`](/style-guide/frontmatter/custom-properties/#pcx_content_type). + +## Components + +### Most used -## Structure +- [`PublicStats`](/style-guide/components/public-stats/): +- [Diagrams](/style-guide/documentation-content-strategy/component-attributes/diagrams/): Particularly helpful for image captions. -### Required components +### Required [**Title**](/style-guide/documentation-content-strategy/component-attributes/titles/): Short verb phrase in second-person imperative. Do not use gerund phrases. [**Reference diagram**](/style-guide/documentation-content-strategy/component-attributes/reference-diagram/): A single diagram that reflects the overall reference architecture. -### Optional components +### Optional [**Notes/warnings**](/style-guide/documentation-content-strategy/component-attributes/notes-tips-warnings/) diff --git a/src/content/docs/style-guide/documentation-content-strategy/content-types/reference-architecture.mdx b/src/content/docs/style-guide/documentation-content-strategy/content-types/reference-architecture.mdx index 0b41c7e9f20307a..7f144b0b32ae192 100644 --- a/src/content/docs/style-guide/documentation-content-strategy/content-types/reference-architecture.mdx +++ b/src/content/docs/style-guide/documentation-content-strategy/content-types/reference-architecture.mdx @@ -4,6 +4,8 @@ title: Reference architecture --- +import { Render } from "~/components"; + ## Purpose The purpose of a reference architecture is to provide a high-level view of how all or part of the Cloudflare platform is built and how Cloudflare products would fit into a customer's existing infrastructure. Reference architectures are designed to show where our platform fits in with a customer's current environment and describe key aspects of a Cloudflare feature/service. Reference architectures should also map customer use cases to Cloudflare solutions. @@ -14,9 +16,13 @@ Reference architectures are typically very detailed. To describe a single archit guiding, straightforward -## content\_type +## content_type + +```yaml +pcx_content_type: reference-architecture +``` -`reference-architecture` +For more details, refer to [`pcx_content_type`](/style-guide/frontmatter/custom-properties/#pcx_content_type). ## Examples @@ -26,9 +32,14 @@ guiding, straightforward [Evolving to a SASE architecture with Cloudflare](/reference-architecture/architectures/sase/) -## Structure +## Components -### Required components +### Most used + +- [`PublicStats`](/style-guide/components/public-stats/): +- [Diagrams](/style-guide/documentation-content-strategy/component-attributes/diagrams/): Particularly helpful for image captions. + +### Required [**Title**](/style-guide/documentation-content-strategy/component-attributes/titles/): Short verb phrase in second-person imperative. Do not use gerund phrases. @@ -38,7 +49,7 @@ guiding, straightforward [**Reference diagram**](/style-guide/documentation-content-strategy/component-attributes/reference-diagram/): A single diagram that reflects the overall reference architecture. -### Optional components +### Optional [**Notes/warnings**](/style-guide/documentation-content-strategy/component-attributes/notes-tips-warnings/) @@ -61,11 +72,11 @@ weight: 1 meta: title: "Reference Architecture: An example Cloudflare solution" --- - + # Cloudflare Reference Architecture - + ## Introduction -Cloudflare provides software as a service solutions (SaaS) solutions for performance, security, reliability, and developer services. This reference architecture focuses on the security of the platform and the network these services are built on, as well as the broad security capabilities the services offer for both public facing and internal facing assets. +Cloudflare provides software as a service solutions (SaaS) solutions for performance, security, reliability, and developer services. This reference architecture focuses on the security of the platform and the network these services are built on, as well as the broad security capabilities the services offer for both public facing and internal facing assets. ### Who is this document for? This reference architecture is designed for IT or security professionals with some responsibility over or familiarity with their organization’s existing infrastructure. It is useful to have some experience with technologies important to securing hybrid work, including identity providers (IdPs), user directories, single sign on (SSO), endpoint security or management (EPP, XDR, UEM, MDM), firewalls, routers, and point solutions like packet or content inspection hardware, threat prevention, and data loss prevention technologies. diff --git a/src/content/docs/style-guide/documentation-content-strategy/content-types/reference.mdx b/src/content/docs/style-guide/documentation-content-strategy/content-types/reference.mdx index 52587eb312f20ed..ef73d3330dd5ee0 100644 --- a/src/content/docs/style-guide/documentation-content-strategy/content-types/reference.mdx +++ b/src/content/docs/style-guide/documentation-content-strategy/content-types/reference.mdx @@ -12,9 +12,13 @@ The purpose of reference content is to provide supplemental information for furt plain, straightforward -## content\_type +## content_type -`reference` +```yaml +pcx_content_type: reference +``` + +For more details, refer to [`pcx_content_type`](/style-guide/frontmatter/custom-properties/#pcx_content_type). ## Structure @@ -54,18 +58,18 @@ Single reference page weight: xx pcx_content_type: reference --- - + # Reference - + Write an overview of the reference information on this page. If this section has child pages, add navigation links below using the DirectoryListing snippet to add links for each child page in a bulleted list. - + - + ## Concise noun title - + Brief description of content in this section. - + ## Concise noun title - + Brief description of content in this section. ``` diff --git a/src/content/docs/style-guide/documentation-content-strategy/content-types/support-content.mdx b/src/content/docs/style-guide/documentation-content-strategy/content-types/support-content.mdx deleted file mode 100644 index 1d343a2c352e347..000000000000000 --- a/src/content/docs/style-guide/documentation-content-strategy/content-types/support-content.mdx +++ /dev/null @@ -1,77 +0,0 @@ ---- -pcx_content_type: concept -title: Support content - ---- - -## Purpose - -The purpose of support content is to provide guidance for solving specific problems with Cloudflare. - -## Tone - -Guiding, straightforward, solution-oriented - -## content_type - -Use the metadata tag for the Content Type you create within the Support tile. - -### Required components - -**Title** - -**Context** - -### Optional components - -**Steps/Tasks/Procedures** - -**Examples** - -**Next steps** - -## Structure - -The structure of a page within the support tile will depend on the purpose that content serves. - -## Boundaries - -The general guidance is that anything related to a specific product (DNS, Security Center) or platform (Cloudflare One) belongs in a [product](/products/) tile. Anything that is specific to interacting with Cloudflare support or details niche troubleshooting steps belongs in the [support](/support/) tile. - -Support content should not duplicate content that already exists in a product tile. - - - - - - - - - - - - - - - - - - - - - - - - - - -
Support content examplesProduct content examples
How to interact with Cloudflare supportProduct documentation - feature information, functionality, configuration, known limitations
Niche troubleshooting information (multiple product configurations affecting each other)Troubleshooting a specific product or platform
Third-party integrations and partnerships that are not specific to a product (like WordPress)Product-specific integration guides
Runtime errors when integrating with external productsRuntime errors specific to a product
How Cloudflare charges for specific things (rates, usage)Process documentation for how to set up billing information, etc. - no pricing content
- -## Additional information - -Migrating content from /support/ to other areas of dev docs - -When you migrate content from the Support tile to other, relevant product areas: - -1. Move over the English version of the page to your desired location. -2. Make edits to bring the content into alignment with our style guide. diff --git a/src/content/docs/style-guide/documentation-content-strategy/content-types/troubleshooting.mdx b/src/content/docs/style-guide/documentation-content-strategy/content-types/troubleshooting.mdx index 8c5fb17666bca12..838458ddb99be66 100644 --- a/src/content/docs/style-guide/documentation-content-strategy/content-types/troubleshooting.mdx +++ b/src/content/docs/style-guide/documentation-content-strategy/content-types/troubleshooting.mdx @@ -16,7 +16,11 @@ Guiding, straightforward, solution-oriented ## content\_type -`troubleshooting` +```yaml +pcx_content_type: troubleshooting +``` + +For more details, refer to [`pcx_content_type`](/style-guide/frontmatter/custom-properties/#pcx_content_type). ## Structure diff --git a/src/content/docs/style-guide/documentation-content-strategy/content-types/tutorial.mdx b/src/content/docs/style-guide/documentation-content-strategy/content-types/tutorial.mdx index 8ee4833f45b981f..e7621bbc8423733 100644 --- a/src/content/docs/style-guide/documentation-content-strategy/content-types/tutorial.mdx +++ b/src/content/docs/style-guide/documentation-content-strategy/content-types/tutorial.mdx @@ -9,10 +9,6 @@ import { GlossaryDefinition, Render } from "~/components"; -## Template - -We have a [tutorial template](https://github.com/cloudflare/cloudflare-docs/blob/production/templates/tutorial-template.mdx) that helps you follow our general structure and content guidelines. - ## Guidelines **A tutorial is:** @@ -40,11 +36,21 @@ Guiding, straightforward, educational, authoritative ### content_type -`tutorial` +```yaml +pcx_content_type: tutorial +``` + +For more details, refer to [`pcx_content_type`](/style-guide/frontmatter/custom-properties/#pcx_content_type). + +### Components + +#### Most used -### Structure +- [`GitHubCode`](/style-guide/components/github-code/) +- [`LastReviewed`](/style-guide/components/last-reviewed/) +- [`ListTutorials`](/style-guide/components/list-tutorials/) -#### Required components +#### Required [**Title**](/style-guide/documentation-content-strategy/component-attributes/titles/): Short verb phrase in second-person imperative. @@ -54,7 +60,7 @@ Guiding, straightforward, educational, authoritative [**Steps**](/style-guide/documentation-content-strategy/component-attributes/steps-tasks-procedures/): Numbered steps that complete a task. -#### Optional components +#### Optional [**Notes/warnings**](/style-guide/documentation-content-strategy/component-attributes/notes-tips-warnings/) diff --git a/src/content/partials/style-guide/directory-listing-definition.mdx b/src/content/partials/style-guide/directory-listing-definition.mdx new file mode 100644 index 000000000000000..e301ae54c2538d0 --- /dev/null +++ b/src/content/partials/style-guide/directory-listing-definition.mdx @@ -0,0 +1,5 @@ +--- +{} +--- + +Use `` to display the directory of a specific folder, which appears as a list of links. \ No newline at end of file diff --git a/src/content/partials/style-guide/public-stats-definition.mdx b/src/content/partials/style-guide/public-stats-definition.mdx new file mode 100644 index 000000000000000..0feedc632bbe330 --- /dev/null +++ b/src/content/partials/style-guide/public-stats-definition.mdx @@ -0,0 +1,5 @@ +--- +{} +--- + +The `PublicStats` component allows you to reference specific values about Cloudflare's network without maintaining those values in multiple files. \ No newline at end of file diff --git a/src/schemas/base.ts b/src/schemas/base.ts index 84715d2f0c23829..24706741e8a6aad 100644 --- a/src/schemas/base.ts +++ b/src/schemas/base.ts @@ -23,24 +23,25 @@ export const baseSchema = ({ image }: SchemaContext) => ), pcx_content_type: z .union([ - z.literal("overview"), + z.literal("api"), + z.literal("changelog"), + z.literal("configuration"), + z.literal("concept"), + z.literal("design-guide"), + z.literal("example"), + z.literal("faq"), z.literal("get-started"), z.literal("how-to"), - z.literal("concept"), + z.literal("integration-guide"), + z.literal("implementation-guide"), + z.literal("learning-unit"), + z.literal("navigation"), + z.literal("overview"), z.literal("reference"), z.literal("reference-architecture"), z.literal("reference-architecture-diagram"), - z.literal("tutorial"), - z.literal("api"), z.literal("troubleshooting"), - z.literal("faq"), - z.literal("integration-guide"), - z.literal("changelog"), - z.literal("configuration"), - z.literal("navigation"), - z.literal("example"), - z.literal("learning-unit"), - z.literal("design-guide"), + z.literal("tutorial"), z.literal("video"), ]) .catch((ctx) => ctx.input)