diff --git a/docs/contributing-to-airbyte/writing-docs.md b/docs/contributing-to-airbyte/writing-docs.md index 6e8e0b21081d..97016f8e6733 100644 --- a/docs/contributing-to-airbyte/writing-docs.md +++ b/docs/contributing-to-airbyte/writing-docs.md @@ -1,3 +1,6 @@ +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + # Updating Documentation We welcome contributions to the Airbyte documentation! @@ -93,6 +96,62 @@ Please familiarize yourself with all the tools available to you when writing doc As a general rule, features that introduce new behavior or prevent certain content from rendering will affect how the Airbyte UI displays markdown content, but have no impact on https://docs.airbyte.com. If you want to test out these in-app features in [a local Airbyte build](https://docs.airbyte.com/contributing-to-airbyte/resources/developing-locally/#develop-on-airbyte-webapp), ensure that you have the `airbyte` git repository checked out to the same parent directory as the airbyte platform repository: if so, development builds will by default fetch connector documentation from your local filesystem, allowing you to freely edit their content and view the rendered output. ::: +#### Select between mutually-exclusive content options with `` +Tabs are a built-in feature of Docusaurus, the tool we use to build `https://docs.airbyte.com`; please refer to [their documentation](https://docusaurus.io/docs/markdown-features/tabs) for their options and behavior in this context. For better site-agnostic documentation, and because we like the feature, we maintain a separate `Tabs` implementation with limited, one-way API compatibility: all usage options we document should behave the same in-app and on `https://docs.airbyte.com`. If you find a discrepancy or breakage, we would appreciate if you [report it as a bug](https://github.com/airbytehq/airbyte/issues/new?assignees=&labels=type%2Fenhancement%2Carea%2Fdocumentation+needs-triage&projects=&template=8-documentation.yaml)! The reverse is not necessarily true, however: Docusaurus supports many use cases besides ours, so supporting its every usage pattern is a deliberate non-goal. + +:::info +Because Docusaurus uses an mdx component, you must include the following import lines in any markdown file which uses tabs: + +```js +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +``` + +This is not optional: if these lines are missing, the documentation site will have errors. They won't show up in the rendered document, however. +::: + +Here's an example set of tabs; note that you can put any number of `...` tags inside a ``. + +```md + + + +When configuring this hypothetical connector using basic HTTP auth, you should mind some tricky security considerations! This just a hypothetical, though, so I never bothered to come up with any. + +As the first tab, this would be shown by default if no `TabItem` were marked as `default`. + + + + +When configuring this hypothetical connector using OAuth authentication, you should do a dance. Good for you! Since it's not the first `TabItem` in its set, we had to explicitly mark this tab as `default` for it to get top billing. + + + +``` + +That renders as the following: + + + + +When configuring this hypothetical connector using basic HTTP auth, you should mind some tricky security considerations! This just a hypothetical, though, so I never bothered to come up with any. + +As the first tab, this would be shown by default if no `TabItem` were marked as `default`. + + + + +When configuring this hypothetical connector using OAuth authentication, you should do a dance. Good for you! Since it's not the first `TabItem` in its set, we had to explicitly mark this tab as `default` for it to get top billing. + + + + +- You don't need to mark any tab as `default` +- If you don't, the first tab (here, Basic HTTP) will be the initial selection instead +- You can use ordinary markdown syntax inside a `TabItem` +- **however**, due to bugs in our in-app markdown rendering library, you should be dilligent about using empty lines to separate different formatting-related things (surrounding tags and their contents, paragraphs vs lists, etc) +- You should also avoid indenting `TabItem` tags and their content according to html conventions, since text indented by four spaces (common for html nested inside two levels of tags) can be interpreted as a code block; different markdown rendering tools can handle this inconsistently. + #### Jump to the relevant documentation section when specific connector setup inputs are focused with `` In the documentation, the relevant section needs to be wrapped in a `` component. When a user focuses the field identified by the `field` attribute in the connector setup UI, the documentation pane will automatically scroll to the associated section of the documentation, highlighting all content contained inside the `` tag. These are rendered as regular divs in the documentation site, so they have no effect in places other than the in-app documentation panel—however, note that there must be blank lines between a custom tag like `FieldAnchor` the content it wraps for the documentation site to render markdown syntax inside the custom tag to html. @@ -135,6 +194,10 @@ The `field` attribute must be a valid json path to one of the properties nested The selection keys are `CDC` and `STANDARD`, so you can wrap a specific replication method's documentation section with a `...` tag, and it will be highlighted if the user selects CDC replication in the UI. +:::tip +Because of their close connection with the connector setup form fields, `` tags are only enabled for the source and destination setup pages. +::: + #### Prevent specific content from rendering in the UI with `` Certain content is important to document, but unhelpful in the context of the Airbyte UI's inline documentation views: - background information that helps users understand a connector but doesn't affect configuration