From 94f043c6a27b5cee68d499a179aa2cafb4d7b921 Mon Sep 17 00:00:00 2001 From: David Cramer Date: Mon, 14 Sep 2020 18:08:43 -0700 Subject: [PATCH] feat: Internal docs (#2275) Co-authored-by: Fiona <61481573+PeloWriter@users.noreply.github.com> --- README.md | 390 +----------------- src/components/internalDocsSidebar.tsx | 39 ++ src/components/sidebar.tsx | 1 + src/docs/internal/environment.mdx | 44 ++ src/docs/internal/index.mdx | 9 + src/docs/internal/onboarding-wizard.mdx | 46 +++ src/docs/internal/pages/components.mdx | 176 ++++++++ src/docs/internal/pages/frontmatter.mdx | 49 +++ src/docs/internal/pages/index.mdx | 28 ++ src/docs/internal/pages/redirects.mdx | 20 + src/docs/internal/pages/search.mdx | 11 + src/docs/internal/pages/variables.mdx | 54 +++ src/docs/internal/platforms/index.mdx | 48 +++ .../createPages/createInternalDocPages.ts | 64 +++ src/templates/doc.tsx | 18 +- 15 files changed, 600 insertions(+), 397 deletions(-) create mode 100644 src/components/internalDocsSidebar.tsx create mode 100644 src/docs/internal/environment.mdx create mode 100644 src/docs/internal/index.mdx create mode 100644 src/docs/internal/onboarding-wizard.mdx create mode 100644 src/docs/internal/pages/components.mdx create mode 100644 src/docs/internal/pages/frontmatter.mdx create mode 100644 src/docs/internal/pages/index.mdx create mode 100644 src/docs/internal/pages/redirects.mdx create mode 100644 src/docs/internal/pages/search.mdx create mode 100644 src/docs/internal/pages/variables.mdx create mode 100644 src/docs/internal/platforms/index.mdx create mode 100644 src/gatsby/createPages/createInternalDocPages.ts diff --git a/README.md b/README.md index 24f25a62a4976..11a3a2c0458b3 100644 --- a/README.md +++ b/README.md @@ -1,391 +1,5 @@ # Sentry Documentation -The Sentry documentation is a static site, generated with [Gatsby][gatsby]. +Take a look at our [Contributing to Docs](https://docs.sentry.io/internal/) documentation to get started. -## Getting started - -You will need [Volta][volta] and [pre-commit][pre-commit] installed. If you don't have opinions about the process, this will get you going: - -```bash -# Install Homebrew and everything mentioned above -$ bin/bootstrap -``` - -Once you have the required system dependencies: - -```bash -# Install or update application dependencies -$ make -``` - -Now run the development webserver: - -```bash -$ yarn start -``` - -You will now be able to access docs via http://localhost:3000. - -[gatsby]: https://gatsbyjs.org -[volta]: https://volta.sh/ -[pre-commit]: https://pre-commit.com/ - -## Markdown Documentation - -Documentation is written in Markdown (via Remark) and MDX. - -[Read the quick reference](https://daringfireball.net/projects/markdown/syntax) - -## Standard Frontmatter - -The standard frontmatter will apply on nearly every page: - -`title` - -: Document title - used in `` as well as things like search titles. - -`noindex` (false) - -: Set this to true to disable indexing (robots, algolia) of this content. - -`notoc` (false) - -: Set this to true to disable table of contents rendering. - -`draft` (false) - -: Set this to true to mark this page as a draft, and hide it from various other components. - -`keywords` ([]) - -: A list of keywords for indexing with search. - -`description` - -: A description to use in the `<meta>` header, as well as in auto generated page grids. - -`sidebar_order` (10) - -: The order of this page in auto generated sidebars and grids. - - -## Redirects - -Redirects are supported via yaml frontmatter in `.md` and `.mdx` files: - -```yaml ---- -redirect_from: - - /performance-monitoring/discover/ ---- -``` - -These will be generated as both client-side (using an empty page with a meta tag) and server-side (nginx rules). - -## Wizard Pages - -A number of pages exist to provide content within Sentry installations. We refer to this system as the _Wizard_. These pages are found in Gatsby's `wizard` content directory, and are rendered and exported to a JSON file for use within the `getsentry/sentry` application. - -Each page consists of some wizard-specific frontmatter, as well as a markdown body: - -```markdown ---- -name: Platform Name -doc_url: Permalink for this page -type: framework -support_level: production ---- - -This is my content. -``` - -## Search - -Search is powered by Algolia, and will index all content in /docs/ that is Markdown or MDX formatted. - -It will _not_ index documents with any of the following in their frontmatter: - -- `draft: true` -- `noindex: true` - -## Notes on Markdown vs MDX - - -:pray: that MDX v2 fixes this. - -MDX has its flaws. When rendering components, any text inside of them is treated as raw text (_not_ markdown). To work around this you can use the `<markdown>` tag, but it also has its issues. Generally speaking, put an empty line after the opening tag, and before the closing tag. - -```jsx -// don't do this as parsing will hit weird breakages -<markdown> -foo bar -</markdown> -``` - -```jsx -// do this -<markdown> - -foo bar - -</markdown> -``` - -## Platform / SDK Docs - -The current generation platform content lives in `src/platforms` and follows some specific rules to generate content. These rules are enforced via the directory structure: - -``` -[platformName]/ - child.mdx - childTwo/ - index.mdx - common/ - aSharedPage.mdx - guides/ - [guideName]/ - uniqueChild.mdx - childTwo/ - index.mdx -``` - -Platforms will generate a list of "guides", and inherit all content within common. Given the above example, we end up with a variety of semi-duplicated URLs: - -``` -/platforms/platformName/ -/platforms/platformName/child/ -/platforms/platformName/childTwo/ -/platforms/platformName/aSharedPage/ -/platforms/platformName/guides/guideName/ -/platforms/platformName/guides/guideName/child/ -/platforms/platformName/guides/guideName/uniqueChild/ -/platforms/platformName/guides/guideName/childTwo/ -/platforms/platformName/guides/guideName/aSharedPage/ -``` - -This is generated by inheriting all content with the ``common/`` directory, then adding (or overriding with) content from the siblings (or children as we'd call them). In the above example, you'll see ``aSharedPage`` is loaded at two different URLs, and ``childTwo`` is overwritten by ``guideName``. - -The sidebar on platform pages (handled by ``<PlatformSidebar>``) will generate with the Guide, or the Base Platform being the primary section, in addition to a list of other guides available in a section below it. This means that all content is focused on the current guide (usually a framework) they're in, ensuring ease of navigation. - -### Globally Shared Content - -In addition to platform-shared content (via ``common/``) you can also defined globally shared content (shared by all platforms and guides). This is done by placing the content into the top-level ``/platforms/common/`` path. It works very much the same as the platform-level common content. - -## Extended Markdown Syntax - -### Variables - -A transformation is exposed to both Markdown and MDX files which supports processing variables in a Django/Jekyll-style way. The variables available are globally scoped and configured within `gatsby-config.js` (via `gatsby-remark-variables`). - -For example: - -```markdown -JavaScript SDK: {{ packages.version('sentry.browser.javascript') }} -``` - -In this case, we expose ``packages`` as an instance of ``PackageRegistry`` which is why there is a `packages.version` function available. Additional, we expose a default context variable of ``page`` which contains the frontmatter of the given markdown node. For example, ``{{ page.title }}``. - -When a function call is invalid (or errors), or doesn't match something in the known scope, it will simple render it as a literal value instead. So for example: - -```markdown -setFingerprint('{{ default }}') -``` - -Will render as: - -```markdown -setFingerprint('{{ default }}') -``` - -This is because there is no entity scoped to ``default`` in the template renderer. Additionally - in this case - we also add the ``default`` expression to the exclusion list in our configuration, as it is commonly use in our documentation. - -### ``packages`` - -The ``packages`` helper is an instance of ``PackageRegistry`` and exposes several methods. - -#### ``packages.version`` - -Returns the latest version of the given package. - -```javascript -packages.version('sentry.javacript.browser') -``` - -You may also optionally specify a fallback for if the package isnt found (or theres an upstream error): - -```javascript -packages.version('sentry.javacript.browser', '1.0.0') -``` - -#### ``packages.checksum`` - -Returns the checksum of a given file in a package. - -```javascript -packages.checksum('sentry.javacript.browser', 'bundle.min.js', 'sha384') -``` - -## Extended MDX Syntax - -We expose several default tags to aid with documentation. - -### Alert - -Render an alert callout. - -Attributes: - -- `title` (string) -- `level` (string) -- `dismiss` (boolean) - -```javascript -<Alert level="info" title="Note"><markdown> - -This is an alert - -</markdown></Alert> -``` - -See also the Note component. - -### ConfigKey - -Render a heading with a configuration key in the correctly cased format for a given platform. - -If content is specified, it will automatically hide the content when the given `platform` is not selected in context. - -Attributes: - -- `name` (string) -- `platform` (string) - defaults to the `platform` value from the page context or querystring -- `supported` (string[]) -- `notSupported` (string[]) - -```javascript -<ConfigKey name="send-default-pii" notSupported={["javascript", "node"]}><markdown> - -Description of send-default-pii - -</markdown></ConfigKey> -``` - -### Code Blocks - -Consecutive code blocks will be automatically collapsed into a tabulated container. This behavior is generally useful if you want to define an example in multiple languages: - - -````markdown -```javascript -function foo() { return 'bar' } -``` - -```python -def foo(): - return 'bar' -``` -```` - -Some times you may not want this behavior. To solve this you can either break up the code blocks with some additional text, or you can use the ``<Break />`` component. - -Additionally code blocks also support `tabTitle` and `filename` properties: - -````markdown -```javascript {tabTitle: Hello} {filename: index.js} -var foo = "bar"; -``` -```` - -### Note - -Render a note. - - -```javascript -<Note><markdown> - -Something important, but maybe not _that_ important. - -</markdown></Note> -``` - -See also the Alert component. - -### PageGrid - -Render all child pages of this document, including their `description` if available. - -```markdown -<PageGrid /> -``` - -### PlatformContent - -Render an include based on the currently selected `platform` in context. - -Attributes: - -- `includePath` (string) - the subfolder within `src/includes` to map to -- `platform` (string) - defaults to the `platform` value from the page context or querystring -- `fallbackPlatform` (string) - default platform for when no content matches - -```javascript -<PlatformContent includePath="sdk-init" /> -``` - -Some notes: - -- When the current platform comes from the page context and no matching include is found, the content will be hidden. - -- When the current platform comes from the page context path (not the querystring) the platform selector dropdown will be hidden. - -- Similar to `PlatformSection`, you can embed content in the block which will render _before_ the given include, but only when an include is available. - -- A file named `_default` will be used if no other content matches. - -Note: This currently causes issues with tableOfContents generation, so its recommended to disable the TOC when using it. - -### PlatformSection - -Render a section based on the currently selected `platform` in context. When the platform is not valid, the content will be hidden. - -Attributes: - -- `platform` (string) - defaults to the `platform` value from the page context or querystring -- `supported` (string[]) -- `notSupported` (string[]) - -```javascript -<PlatformSection notSupported={["javascript", "node"]}><markdown> - -Something that applies to all platforms, but not javascript or node. - -</PlatformSection></ConfigKey> -``` - -Note: This currently causes issues with tableOfContents generation, so its recommended to disable the TOC when using it. - -### PlatformLink - -Useful for linking to platform-specific content when there's not a specific platform already selected. - -```javascript - -<PlatformLink to="/enriching-error-data/" /> -``` - -This will direct them to a page where they can choose the platform, and then to the appropriate link. If they're within a page that already has an active platform, it will simply link to the appropriate page and skip the redirect. - -## Linting - -We use prettier to format our code. Run prettier if you get linting errors in CI. - -```bash -yarn prettier:fix -``` - -If you want to run prettier on mdx and markdown files, run - -```bash -yarn prettier:fix:all -``` +Note: The documentation for this repository is self-hosted via `src/internal/`. diff --git a/src/components/internalDocsSidebar.tsx b/src/components/internalDocsSidebar.tsx new file mode 100644 index 0000000000000..5971c37442269 --- /dev/null +++ b/src/components/internalDocsSidebar.tsx @@ -0,0 +1,39 @@ +import React from "react"; +import { useStaticQuery, graphql } from "gatsby"; + +import DynamicNav, { toTree } from "./dynamicNav"; + +const query = graphql` + query InternalDocsSidebarQuery { + allSitePage( + filter: { + path: { regex: "/internal/" } + context: { draft: { ne: false } } + } + ) { + nodes { + path + context { + draft + title + sidebar_order + } + } + } + } +`; + +export default (): JSX.Element => { + const data = useStaticQuery(query); + const tree = toTree(data.allSitePage.nodes.filter(n => !!n.context)); + return ( + <ul className="list-unstyled" data-sidebar-tree> + <DynamicNav + root="internal" + title="Contributing to Docs" + tree={tree} + showDepth={2} + /> + </ul> + ); +}; diff --git a/src/components/sidebar.tsx b/src/components/sidebar.tsx index d6a75f216e93a..18fac6fc8a603 100644 --- a/src/components/sidebar.tsx +++ b/src/components/sidebar.tsx @@ -61,6 +61,7 @@ export const Sidebar = ({ data }: ChildProps): JSX.Element => { <SidebarLink to="/platforms/">Platforms</SidebarLink> <SidebarLink to="/clients/">Legacy SDKs</SidebarLink> <SidebarLink to="/api/">API Reference</SidebarLink> + <SidebarLink to="/internal/">Contributing to Docs</SidebarLink> <SidebarLink to="https://develop.sentry.dev"> Developer Documentation </SidebarLink> diff --git a/src/docs/internal/environment.mdx b/src/docs/internal/environment.mdx new file mode 100644 index 0000000000000..8225b185e582d --- /dev/null +++ b/src/docs/internal/environment.mdx @@ -0,0 +1,44 @@ +--- +title: Development Environment +noindex: true +--- + +You will need [Volta][volta] and [pre-commit][pre-commit] installed. If you don't have opinions about the process, this will get you going: + +```bash +# Install Homebrew and everything mentioned above +$ bin/bootstrap +``` + +Once you have the required system dependencies: + +```bash +# Install or update application dependencies +$ make +``` + +Now run the development webserver: + +```bash +$ yarn start +``` + +You will now be able to access docs via http://localhost:3000. + +[gatsby]: https://gatsbyjs.org +[volta]: https://volta.sh/ +[pre-commit]: https://pre-commit.com/ + +## Linting + +We use prettier to format our code. Run prettier if you get linting errors in CI. + +```bash +yarn prettier:fix +``` + +If you want to run prettier on mdx and markdown files, run + +```bash +yarn prettier:fix:all +``` diff --git a/src/docs/internal/index.mdx b/src/docs/internal/index.mdx new file mode 100644 index 0000000000000..f7d124a10c3c9 --- /dev/null +++ b/src/docs/internal/index.mdx @@ -0,0 +1,9 @@ +--- +title: Contributing to Docs +sidebar_order: 10000 +noindex: true +--- + +The Sentry documentation is a static site, generated with [Gatsby][gatsby]. + +<PageGrid /> diff --git a/src/docs/internal/onboarding-wizard.mdx b/src/docs/internal/onboarding-wizard.mdx new file mode 100644 index 0000000000000..0e532fd9ec433 --- /dev/null +++ b/src/docs/internal/onboarding-wizard.mdx @@ -0,0 +1,46 @@ +--- +title: Onboarding Wizard +noindex: true +sidebar_order: 1000 +--- + +The docs repository is responsible for a piece of functionality in the Sentry product most commonly referred to as _the Wizard_. More precisely, the product pulls in documentation about SDK configuration in part of its project creation / onboarding process. + +The content for the onboarding wizard is located in `src/wizard`, and follows slightly different rules than other pages: + +- It is markdown _only_. MDX is not currently supported. +- It is exported as plain HTML (encoded as JSON), thus styles need to exist within Sentry itself. +- The exposed frontmatter is specific to the wizard. + +## Directory Structure + +The directory structure directly influences how content is exposed within onboarding. It takes the form of: + +```bash +src/wizard +src/wizard/{platform}/index.md +src/wizard/{platform}/{guide}.md +``` + +The `index.md` is exposed the root platform instructions, and `{guide}.md` is exposed as a child integration of the platform. This functions similarly to the [platform pages](../pages/platforms). + +## Page Format + +Each page consists of some wizard-specific frontmatter, as well as a markdown body: + +```markdown {filename:src/wizard/platform/index.md} +--- +name: Platform Name +doc_url: Permalink for this page +type: framework +support_level: production +--- + +This is my content. +``` + +<Note><markdown> + +Wizard content is only supported with native markdown (not MDX), thus only with a `.md` extension. + +</markdown></Note> diff --git a/src/docs/internal/pages/components.mdx b/src/docs/internal/pages/components.mdx new file mode 100644 index 0000000000000..12a186850fa4f --- /dev/null +++ b/src/docs/internal/pages/components.mdx @@ -0,0 +1,176 @@ +--- +title: MDX Components +noindex: true +--- + +## Alert + +Render an alert callout. + +<Alert level="info" title="Note"><markdown> + +This is an alert + +</markdown></Alert> + +```markdown {tabTitle:Example} +<Alert level="info" title="Note"> +<markdown> + +This is an alert + +</markdown> +</Alert> +``` + +Attributes: + +- `title` (string) +- `level` (string) +- `dismiss` (boolean) + +See also the Note component. + +## ConfigKey + +Render a heading with a configuration key in the correctly cased format for a given platform. + +<Note><markdown> + +If content is specified, it will automatically hide the content when the given `platform` is not selected in context. + +</markdown></Note> + +```markdown {tabTitle:Example} +<ConfigKey name="send-default-pii" notSupported={["javascript", "node"]}> +<markdown> + +Description of send-default-pii + +</markdown> +</ConfigKey> +``` + +Attributes: + +- `name` (string) +- `platform` (string) - defaults to the `platform` value from the page context or querystring +- `supported` (string[]) +- `notSupported` (string[]) + +## Code Blocks + +Consecutive code blocks will be automatically collapsed into a tabulated container. This behavior is generally useful if you want to define an example in multiple languages: + +````markdown {tabTitle:Example} +```javascript +function foo() { + return "bar"; +} +``` + +```python +def foo(): + return 'bar' +``` +```` + +Sometimes you may not want this behavior. To solve this, you can either break up the code blocks with some additional text, or use the `<Break />` component. + +Additionally code blocks also support `tabTitle` and `filename` properties: + +````markdown {tabTitle:Example} +```javascript {tabTitle: Hello} {filename: index.js} +var foo = "bar"; +``` +```` + +## Note + +Render a note. + +<Note> +<markdown> + +Something important, but maybe not _that_ important. + +</markdown> +</Note> + +```markdown {tabTitle:Example} +<Note> +<markdown> + +Something important, but maybe not _that_ important. + +</markdown> +</Note> +``` + +See also the [Alert component](#alert). + +## PageGrid + +Render all child pages of this document, including their `description` if available. + +```markdown {tabTitle:Example} +<PageGrid /> +``` + +## PlatformContent + +Render an include based on the currently selected `platform` in context. + +```markdown {tabTitle:Example} +<PlatformContent includePath="sdk-init" /> +``` + +Attributes: + +- `includePath` (string) - the subfolder within `src/includes` to map to +- `platform` (string) - defaults to the `platform` value from the page context or querystring +- `fallbackPlatform` (string) - default platform for when no content matches + +Some notes: + +- When the current platform comes from the page context and no matching include is found, the content will be hidden. + +- When the current platform comes from the page context path (not the querystring) the platform selector dropdown will be hidden. + +- Similar to `PlatformSection`, you can embed content in the block which will render _before_ the given include, but only when an include is available. + +- A file named `_default` will be used if no other content matches. + +Note: This currently causes issues with tableOfContents generation, so its recommended to disable the TOC when using it. + +## PlatformSection + +Render a section based on the currently selected `platform` in context. When the platform is not valid, the content will be hidden. + +```markdown {tabTitle:Example} +<PlatformSection notSupported={["javascript", "node"]}> +<markdown> + +Something that applies to all platforms, but not javascript or node. + +</markdown> +</PlatformSection> +``` + +Attributes: + +- `platform` (string) - defaults to the `platform` value from the page context or querystring +- `supported` (string[]) +- `notSupported` (string[]) + +Note: This currently causes issues with tableOfContents generation, so we recommend disabling the TOC when using it. + +## PlatformLink + +Useful for linking to platform-specific content when there's not a specific platform already selected. + +```markdown {tabTitle:Example} +<PlatformLink to="/enriching-error-data/" /> +``` + +This will direct users to a page where they can choose the platform, and then to the appropriate link. If they're within a page that already has an active platform, it will simply link to the appropriate page and skip the redirect. diff --git a/src/docs/internal/pages/frontmatter.mdx b/src/docs/internal/pages/frontmatter.mdx new file mode 100644 index 0000000000000..ef12329d3d1d4 --- /dev/null +++ b/src/docs/internal/pages/frontmatter.mdx @@ -0,0 +1,49 @@ +--- +title: Frontmatter +noindex: true +--- + +Frontmatter a YAML-formatted blob defined at the top of every markdown or mdx file: + +```markdown +--- +title: Doc Title +--- + +Markdown or MDX content +``` + +Standard frontmatter will apply on nearly every page: + +`title` + +: Document title - used in `<title>` as well as things like search titles. + +`noindex` (false) + +: Set this to true to disable indexing (robots, algolia) of this content. + +`notoc` (false) + +: Set this to true to disable table of contents rendering. + +`draft` (false) + +: Set this to true to mark this page as a draft, and hide it from various other components. + +`keywords` ([]) + +: A list of keywords for indexing with search. + +`description` + +: A description to use in the `<meta>` header, as well as in auto generated page grids. + +`sidebar_order` (10) + +: The order of this page in auto generated sidebars and grids. + +Much of the other functionality for pages is also driven via frontmatter, such as: + +- [Redirects](../redirects/) +- [Search](../search/) diff --git a/src/docs/internal/pages/index.mdx b/src/docs/internal/pages/index.mdx new file mode 100644 index 0000000000000..d052000cedbce --- /dev/null +++ b/src/docs/internal/pages/index.mdx @@ -0,0 +1,28 @@ +--- +title: Pages +noindex: true +--- + +Documentation is written in Markdown (via Remark) and MDX. + +[<kbd>Read the quick reference</kbd>](https://daringfireball.net/projects/markdown/syntax) + +## Markdown vs MDX + +:pray: that MDX v2 fixes this. + +MDX has its flaws. When rendering components, any text inside of them is treated as raw text (_not_ markdown). To work around this you can use the `<markdown>` tag, but it also has its issues. Generally speaking, put an empty line after the opening tag, and before the closing tag. + +```jsx +// don't do this as parsing will hit weird breakages +<markdown>foo bar</markdown> +``` + +```jsx +// do this +<markdown>foo bar</markdown> +``` + +## Additional Topics + +<PageGrid /> diff --git a/src/docs/internal/pages/redirects.mdx b/src/docs/internal/pages/redirects.mdx new file mode 100644 index 0000000000000..1c13fda855802 --- /dev/null +++ b/src/docs/internal/pages/redirects.mdx @@ -0,0 +1,20 @@ +--- +title: Redirects +noindex: true +--- + +Redirects are supported via yaml frontmatter in `.md` and `.mdx` files: + +```yaml +--- +redirect_from: + - /performance-monitoring/discover/ +--- + +``` + +These will be generated as both client-side (using an empty page with a meta tag) and server-side (nginx rules). + +## Vercel + +Because docs.sentry.io is hosted on Vercel, there are also some wider-reaching redirects implemented to cover legacy URLs which cannot be re-implemented using `redirect_from`. See `vercel.json` for these. diff --git a/src/docs/internal/pages/search.mdx b/src/docs/internal/pages/search.mdx new file mode 100644 index 0000000000000..d19c375189f7f --- /dev/null +++ b/src/docs/internal/pages/search.mdx @@ -0,0 +1,11 @@ +--- +title: Search +noindex: true +--- + +Search is powered by Algolia, and will index all content in /docs/ that is Markdown or MDX formatted. + +It will _not_ index documents with any of the following in their frontmatter: + +- `draft: true` +- `noindex: true` diff --git a/src/docs/internal/pages/variables.mdx b/src/docs/internal/pages/variables.mdx new file mode 100644 index 0000000000000..bc3ca496aed4d --- /dev/null +++ b/src/docs/internal/pages/variables.mdx @@ -0,0 +1,54 @@ +--- +title: Markdown Variables +noindex: true +--- + +A transformation is exposed to both Markdown and MDX files which supports processing variables in a Django/Jekyll-style way. The variables available are globally scoped and configured within `gatsby-config.js` (via `gatsby-remark-variables`). + +For example: + +```markdown +JavaScript SDK: {{ packages.version('sentry.browser.javascript') }} +``` + +In this case, we expose `packages` as an instance of `PackageRegistry` which is why there is a `packages.version` function available. Additional, we expose a default context variable of `page` which contains the frontmatter of the given markdown node. For example, `{{ page.title }}`. + +When a function call is invalid (or errors), or doesn't match something in the known scope, it will simple render it as a literal value instead. So for example: + +```markdown +setFingerprint('{{ default }}') +``` + +Will render as: + +```markdown +setFingerprint('{{ default }}') +``` + +This is because there is no entity scoped to `default` in the template renderer. Additionally - in this case - we also add the `default` expression to the exclusion list in our configuration, as it is commonly use in our documentation. + +## `packages` + +The `packages` helper is an instance of `PackageRegistry` and exposes several methods. + +### `packages.version` + +Returns the latest version of the given package. + +```javascript +packages.version("sentry.javacript.browser"); +``` + +You may also optionally specify a fallback for if the package isnt found (or theres an upstream error): + +```javascript +packages.version("sentry.javacript.browser", "1.0.0"); +``` + +### `packages.checksum` + +Returns the checksum of a given file in a package. + +```javascript +packages.checksum("sentry.javacript.browser", "bundle.min.js", "sha384"); +``` diff --git a/src/docs/internal/platforms/index.mdx b/src/docs/internal/platforms/index.mdx new file mode 100644 index 0000000000000..caa967ffcfbb8 --- /dev/null +++ b/src/docs/internal/platforms/index.mdx @@ -0,0 +1,48 @@ +--- +title: Platform Portals +noindex: true +--- + +Platform content lives in `src/platforms` and follows some specific rules to generate content. The content is rendered using the same features as all other [pages](../), but has some additional functionality exposed to clone content and encapsulate platforms as portals. + +Directory structure has meaning within the platforms directory, and looks something akin to: + +``` +[platformName]/ + child.mdx + childTwo/ + index.mdx + common/ + aSharedPage.mdx + guides/ + [guideName]/ + uniqueChild.mdx + childTwo/ + index.mdx +``` + +Platforms will generate a list of "guides", and inherit all content within common. Given the above example, we end up with a variety of semi-duplicated URLs: + +``` +/platforms/platformName/ +/platforms/platformName/child/ +/platforms/platformName/childTwo/ +/platforms/platformName/aSharedPage/ +/platforms/platformName/guides/guideName/ +/platforms/platformName/guides/guideName/child/ +/platforms/platformName/guides/guideName/uniqueChild/ +/platforms/platformName/guides/guideName/childTwo/ +/platforms/platformName/guides/guideName/aSharedPage/ +``` + +This is generated by inheriting all content with the `common/` directory, then adding (or overriding with) content from the siblings (or children as we'd call them). In the above example, you'll see `aSharedPage` is loaded at two different URLs, and `childTwo` is overwritten by `guideName`. + +The sidebar on platform pages (handled by `<PlatformSidebar>`) will generate with the Guide, or the Base Platform being the primary section, in addition to a list of other guides available in a section below it. This means that all content is focused on the current guide (usually a framework) they're in, ensuring ease of navigation. + +## Globally Shared Content + +In addition to platform-shared content (via `common/`) you can also defined globally shared content (shared by all platforms and guides). This is done by placing the content into the top-level `/platforms/common/` path. It works very much the same as the platform-level common content. + +## Platform-Specific Components + +There are a number of components that aid the development of platform specific pages, as well as behave differently when a platform is active. For more information, see [components](../components/). diff --git a/src/gatsby/createPages/createInternalDocPages.ts b/src/gatsby/createPages/createInternalDocPages.ts new file mode 100644 index 0000000000000..490e56fd1f5a4 --- /dev/null +++ b/src/gatsby/createPages/createInternalDocPages.ts @@ -0,0 +1,64 @@ +import { getChild, getDataOrPanic } from "../helpers"; + +export default async ({ actions, graphql, reporter }) => { + const data = await getDataOrPanic( + ` + query { + allFile(filter: { sourceInstanceName: { eq: "docs" } }) { + nodes { + id + childMarkdownRemark { + frontmatter { + title + description + draft + noindex + sidebar_order + redirect_from + } + fields { + slug + legacy + } + excerpt(pruneLength: 5000) + } + childMdx { + frontmatter { + title + description + draft + noindex + sidebar_order + redirect_from + } + fields { + slug + legacy + } + excerpt(pruneLength: 5000) + } + } + } + } + `, + graphql, + reporter + ); + + const component = require.resolve(`../../templates/internal-doc.tsx`); + data.allFile.nodes.map((node: any) => { + const child = getChild(node); + if (child && child.fields) { + actions.createPage({ + path: child.fields.slug, + component, + context: { + excerpt: child.excerpt, + ...child.frontmatter, + id: node.id, + legacy: child.fields.legacy, + }, + }); + } + }); +}; diff --git a/src/templates/doc.tsx b/src/templates/doc.tsx index 1ff0cd32382c0..a378f145b510b 100644 --- a/src/templates/doc.tsx +++ b/src/templates/doc.tsx @@ -4,17 +4,17 @@ import { graphql } from "gatsby"; import BasePage from "~src/components/basePage"; import Content from "~src/components/content"; import DevelopmentApiSidebar from "~src/components/developmentApiSidebar"; +import InternalDocsSidebar from "~src/components/internalDocsSidebar"; -export default props => { +export default (props: any) => { + let sidebar = null; + if (props.path.startsWith("/development-api/")) { + sidebar = <DevelopmentApiSidebar />; + } else if (props.path.startsWith("/internal/")) { + sidebar = <InternalDocsSidebar />; + } return ( - <BasePage - sidebar={ - props.path.startsWith("/development-api") ? ( - <DevelopmentApiSidebar /> - ) : null - } - {...props} - > + <BasePage sidebar={sidebar} {...props}> <Content file={props.data.file} /> </BasePage> );