Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 8 additions & 7 deletions apps/docs/src/content/docs/en/pages/style-guide/components.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -106,12 +106,12 @@ import Code from '~/components/webkit/CodeBlock.vue'
```

- `client:visible` is mandatory. Without it the tabs render and do not switch.
- A block pairs each `tab.x` with a `panel.x`. The one exception is a page that documents more than one interface, such as a [Quickstart page](/en/documentation/style-guide/content/quickstart/) or a [how-to guide](/en/documentation/style-guide/content/how-to-guides/): the prerequisites block declares the tab strip, and every later block of the same `sharedStore` holds only `panel.x` slots. A panel-only block of the `interface` store renders that strip above its own panels, so the reader switches at any section.
- A block pairs each `tab.x` with a `panel.x`. The one exception is a page that documents more than one interface, such as a [Quickstart page](/en/documentation/style-guide/content/quickstart/) or a [how-to guide](/en/documentation/style-guide/content/how-to-guides/). On that page, the prerequisites block declares the tab strip, and every later block of the same `sharedStore` holds only `panel.x` slots. A panel-only block of the `interface` store renders that strip above its own panels, so the reader switches at any section.
- **Blank lines around markdown inside a Fragment are mandatory**, or the markdown renders as one literal paragraph.
- Panels are paired to tabs by key, and the first tab is the default. An `interface` block renders its tabs in one order on every page, whatever order the MDX declares them in: Console, GraphiQL, CLI, GitHub, API. Write them in that order anyway, so the page and its Markdown twin read the same.
- Canonical keys: `tab.console`, `tab.api`, `tab.cli`, plus `tab.apiv3` / `tab.apiv4` for versioned APIs. A key is lowercase letters and digits only: a hyphen escapes the `tab.x` / `panel.x` pairing check without failing it.
- In a block with `sharedStore="interface"`, open every panel with a heading one level below the section it sits in, carrying the tab label: `### Console`. These headings stay out of the table of contents, and each one links to its section with its interface selected: `?interface=console#create-a-database`.
- Optional `sharedStore="<key>"` syncs selection across tab groups on a page. Interface tabs use `sharedStore="interface"`, so one selection follows the reader down a page that repeats the tabs per section, and on to the next page: that one store is kept in the browser and written to the URL as `?interface=<key>`, which leaves the fragment free for a section. Give every block sharing a key the same tabs. A block that does not offer the selected key shows its own first panel instead, and leaves the selection untouched for the blocks that do offer it.
- Optional `sharedStore="<key>"` syncs selection across tab groups on a page. Interface tabs use `sharedStore="interface"`, so one selection follows the reader down a page that repeats the tabs per section, and on to the next page. That one store is kept in the browser and written to the URL as `?interface=<key>`, which leaves the fragment free for a section. Give every block sharing a key the same tabs. A block that does not offer the selected key shows its own first panel instead, and leaves the selection untouched for the blocks that do offer it.

## Tag

Expand Down Expand Up @@ -163,7 +163,7 @@ Every diagram follows the same rules:

- **Open with the shared `init` line** the example shows. It lays the diagram out with ELK, gives the labels room, and shrinks a diagram wider than the column to fit it. When the first node does not render at the top, add an `elk` object right after `"layout": "elk",`. In a diagram with a cycle, such as a request and its response, use ELK's model-order options, so the declaration order decides the layers: `"cycleBreakingStrategy": "MODEL_ORDER"`, or `"preset": "modelOrder", "keepEntryNodeOnTop": true`. In a diagram with more than one starting node, use `"layeringStrategy": "LONGEST_PATH_SOURCE"`, which puts every starting node in the top row.
- **Run every flowchart top to bottom** (`flowchart TD`), a chain of steps included. A chain drawn left to right grows wider than the column and shrinks its labels to fit.
- **Give each role one shape.** The client is a stadium (`(["Client"])`), anything on Azion, a Product or a Platform Resource, is a rectangle (`["application"]`), a data store is a cylinder (`[("KV Store")]`), and a system outside Azion is a subroutine (`[["origin server"]]`). A step, a state, or a decision keeps its rectangle or its diamond.
- **Give each role one shape.** The client is a stadium (`(["Client"])`). Anything on Azion, a Product or a Platform Resource, is a rectangle (`["application"]`). A data store is a cylinder (`[("KV Store")]`), and a system outside Azion is a subroutine (`[["origin server"]]`). A step, a state, or a decision keeps its rectangle or its diamond.
- **Let the line style say which way the flow runs.** When a diagram draws a request and its response, solid arrows (`-->`) carry the request and dotted arrows (`-.->`) carry the response. A flow that runs apart from any request, such as a purge or a log stream, takes thick arrows (`==>`).

## Steps
Expand Down Expand Up @@ -252,20 +252,20 @@ import DocItem from '@aziontech/webkit/doc-item'

## Changelog entry

One dated entry: label and version on the left, the notes on the right, with an anchor built from the label.
One dated entry: label and version on the left, the notes on the right, and an anchor on the label.

```mdx
import DocUpdate from '@aziontech/webkit/doc-update'

<DocUpdate label="July 10, 2026" description="Version 1.3.0" tags={['Marketplace']}>
<DocUpdate label="July 10, 2026" description="Version 1.3.0" tags={['Marketplace']} anchor="july-10-2026">

**Bot Manager** now ships nine new static rules and two new arguments.

</DocUpdate>
```

- No client directive. Blank lines around the markdown inside are mandatory.
- `label` is the anchor, slugified. Two entries with the same label need distinct `anchor` values.
- Always pass `anchor`. The right rail lists only the entries that carry one, and without it the id falls back to the slugified `label`. Two entries with the same label need distinct `anchor` values.
- `description` is the line under the label; `tags` is an array of short labels.
- A page of entries outlines them: the right rail lists one row per date and links the first entry with that date, in place of the headings inside the notes. The [Changelog](/en/documentation/style-guide/content/changelog/) pattern holds the rest.

Expand Down Expand Up @@ -325,7 +325,7 @@ A page about a resource that exists in API v3 and API v4 carries exactly one ver
| `versionDualSteps` | The end of the introduction of a guide with steps for API v4 and API v3 | None | API v4 reaches every account. The API v3 steps go with it |
| `versionDeprecated` | The top of an API v3 page | A link to the API v4 page, titled as that page | API v4 reaches every account. The page then redirects to its API v4 counterpart, never to a home page |

An API v3 page is not listed in the navigation. Its row in the navigation tree carries `"hidden": true`, so the page keeps the sidebar and breadcrumb of its Platform Resource, and readers reach it from the notice on its API v4 counterpart.
An API v3 page is not listed in the navigation. Its row in the navigation tree carries `"hidden": true`, so the page keeps the sidebar and breadcrumb of its Platform Resource. Readers reach it from the notice on its API v4 counterpart.

The date when API v3 shuts down appears only in `versionDeprecated` and on [API v4 Migration](/en/documentation/fundamentals/api-v4-migration/).

Expand All @@ -345,6 +345,7 @@ import ProductGuidesSection from '~/components/ProductGuidesSection.astro'

- `product` — the section's id, such as `applications`. The table lists every guide the guides catalog tags with the section or with a Platform Resource nested in it.
- The date is the page's last change, filled in for you. Never write it by hand.
- The table also lists the videos that the navigation's video list tags with the section. A video row opens YouTube in a new tab, its type adds Video, and its date stays empty.
- The type column shows each page's content type, in the reader's language.
- Rows sort alphabetically by each page's navigation label, in the reader's language, never by date. The name column shows that label, not the page title.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Write an architecture page when:
Do not write an architecture page when:

- The subject is one Platform Resource or one idea. Write a [concept page](/en/documentation/style-guide/content/concept/).
- The reader wants to build the thing. Write the [use-case page](/en/documentation/style-guide/content/use-cases/) that builds it, or a [multi-resource guide](/en/documentation/style-guide/content/multi-resource-guides/), and link it from here.
- The reader wants to build the thing. Write the [use-case page](/en/documentation/style-guide/content/use-cases/) that explains it and links the guides that build it, or a [multi-resource guide](/en/documentation/style-guide/content/multi-resource-guides/), and link it from here.
- The catalog has no entry for the design. Propose it to the Use Case catalog first; the page comes after the entry.
- The design cannot be drawn. A design you cannot draw is one you do not yet understand well enough to publish.

Expand Down Expand Up @@ -153,7 +153,7 @@ Content moves through the design in this order:
The publish flow moves only on a push, and the two flows meet only at the bucket.
````

## Related
## Related resources

<FrameBox>
<ItemList>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ import DocItem from '@aziontech/webkit/doc-item'

## Purpose

A changelog records notable changes to the platform, newest first. It is a **record**, not one of the four Diátaxis forms: it does not teach, instruct, or explain, and a reader consults it to answer one question, which is what changed and when.
A changelog records notable changes to the platform, newest first. It is a **record**, not one of the four Diátaxis forms: it does not teach, instruct, or explain. A reader consults it to answer one question, which is what changed and when.

## When to use

Expand All @@ -36,15 +36,16 @@ Each entry is one `DocUpdate`: the date, the version, and the Platform Resource

**Required components**

- **A `DocUpdate` entry**, newest first. `label` is the date, `<Month> <day>, <year>`: dates are allowed in changelogs and only in changelogs. `anchor` is the date as a slug, `july-10-2026`.
- **A `DocUpdate` entry**, newest first. `label` is the date, `<Month> <day>, <year>`: a changelog is one of the few places [Numbers and units](/en/documentation/style-guide/formatting/numbers/#format-a-date-only-where-a-date-belongs) allows a date. `anchor` is the date as a slug, `july-10-2026`.
- **One tag**: `tags={['<tag>']}`, exactly one. The tag is the current name of the Platform Resource or channel the entry reports on. It comes from the closed list in the [contributing guide](https://github.com/aziontech/docs/blob/main/.github/CONTRIBUTING.md#changelog-entries).
- **The opening sentence**: `**<Platform Resource>** now <verb>s <what it now does>.`, plus the concrete detail: the flag, the field, or the default. When the change belongs to a Platform Resource nested in another, the nested one is the subject.
- **What it means concretely**: what works without configuration now, or what behaves differently.
- **Who is not affected**: existing configurations, earlier versions, accounts that did not opt in.
- **The closing link**: `For more information, refer to [<the documenting page>](/en/documentation/.../).`

**Optional components**

- **The Platform Resource and the version**: `tags={['<Platform Resource>']}` and `description="Version <x.y.z>"`, when the release names a Platform Resource or a version.
- **The version**: `description="Version <x.y.z>"`, when the release has a version.
- **Kind headings**: `### Features`, `### Improvements`, `### Bug Fixes` inside the notes, when one entry lists more than one kind of change.
- **Migration or opt-in steps**: with a code sample, when an API, CLI, or configuration changed.

Expand All @@ -53,7 +54,7 @@ Each entry is one `DocUpdate`: the date, the version, and the Platform Resource
```mdx
import DocUpdate from '@aziontech/webkit/doc-update'

<DocUpdate label="<Month> <day>, <year>" description="Version <x.y.z, when there is one>" tags={['<Platform Resource>']} anchor="<month>-<day>-<year>">
<DocUpdate label="<Month> <day>, <year>" description="Version <x.y.z, when there is one>" tags={['<tag>']} anchor="<month>-<day>-<year>">

**<Platform Resource>** now <verb>s <what it now does>, <the concrete detail: the flag, field, or default>.

Expand All @@ -74,15 +75,16 @@ For more information, refer to [<the documenting page>](/en/documentation/.../).
- **State who is not affected.** A reader's first question about any change is whether it breaks them; answer it before they ask.
- **Show migration or opt-in steps when the surface changed.** An API, CLI, or configuration change gets a code sample; two lines is enough.
- **Close every entry with the documentation link.** An entry that documents the feature in full is a page filed in the wrong place.
- **Give every entry an `anchor`.** The page outline lists one row per date and links the first entry with that date, so `#<date>` keeps resolving. A second entry on the same date takes `<date>-<resource>`: `july-10-2026-marketplace`.
- **Give every entry an `anchor`.** The page outline lists one row per date and links the first entry with that date, so `#<date>` keeps resolving. A second entry on the same date takes `<date>-<tag>`, with the tag as a slug: `july-10-2026-marketplace`.
- **Add a tag to the closed list before you use it.** A release that needs a new tag adds it to the list in the contributing guide. The same pull request adds it to the changelog check. `pnpm lint:changelog` reports a new entry that does not carry exactly one tag from the list.
- **Leave a blank line after the opening tag and before the closing one.** Without them the notes render as one literal paragraph.
- **Never rewrite an entry.** Correct it with a new dated entry; the log is append-only.
- **Keep the names of the period.** A dated record keeps the names it was written with; only new entries use current names.
- **End the page with its oldest entry.** A changelog has no closing section: no Next steps and no Related resources.

## Examples

- [Changelog archive](/en/documentation/changelog/previous-year/): one entry per month, from 2016 to 2021.
- [Changelog archive](/en/documentation/changelog/previous-year/): the entries from before the current release notes, one per month.

This trimmed entry shows the date, the tag, and the entry shape:

Expand All @@ -100,7 +102,7 @@ For more information, refer to [Azion Bot Manager Lite](/en/documentation/platfo
</DocUpdate>
```

## Related
## Related resources

<FrameBox>
<ItemList>
Expand Down
Loading
Loading