`) or code blocks (```), so there are regular expressions added to ignore anything inside of these.
- An **entire line**, add the following comment above it:
- ```markdown
-
+ ```mdx
+ {/* cspell:disable-next-line */}
```
- **Multiple lines**, add comments above and below the lines to be ignored:
- ```markdown
-
+ ```mdx
+ {/* cspell:disable */}
- Everything inside of these comments will be ignored by the spell checkr. Proofread your own words carefully.
+Everything inside of these comments will be ignored by the spell checker. Proofread your own words carefully.
- + {/* cspell:enable */} ``` > [!IMPORTANT] @@ -87,11 +139,25 @@ Comments disabling the next line or entire sections of documentation are useful In general, we should try to avoid ignoring words unless they are technical terms that are used throughout the documentation and wouldn't necessarily make sense formatted as code. +### Heading IDs + +Every heading in `docs/` needs an explicit ID, so that renaming the heading doesn't change its anchor and break links to it: + +```mdx +## Basic Usage {/* #basic-usage */} +``` + +Run the following command to add IDs to any new headings, and then push the changes. CI fails if a heading is missing one. + +``` +npm run heading-ids +``` + --- ## Using VS Code on Windows -The Ionic docs were originally built in a Mac-based environment, so Mac-focused linting rules apply when committing changes. To contribute on Windows, do the following: +Prettier expects LF line endings, and CI fails if `npm run lint` changes any file. To contribute on Windows, do the following: - Configure VS Code to read/save files using line breaks (LF) instead of carriage returns (CRLF). Set it globally by navigating to: Settings -> Text Editor -> Files -> Eol. Set to `\n`. - Check that the Git setting `core.autocrlf` is set to `false`: run `git config -l | grep autocrlf`. Switch it to false using: `git config --global core.autocrlf false`. @@ -103,14 +169,19 @@ Ionic's documentation is built using [Docusaurus](https://docusaurus.io/). The c ### Directories +- `_templates/` - templates used by `npm run playground:new` +- `docs/` - content of the current version of the docs +- `plugins/` - local Docusaurus plugins, such as the one that generates the component API pages - `scripts/` - build scripts used to generate markdown or json files -- `src/` - source code and content of the docs +- `src/` - source code of the site - `components/` - components used across the site - `global/` - components used globally - `page/` - components used on a single page or in a limited scope - `styles/` - global styles and variables - `components/` - styles split out into the components they target + - `theme/` - Docusaurus theme components that have been swizzled - `static/` + - `code/` - StackBlitz project templates used by the playgrounds - `demos/` - self-contained demos, optionally presented by pages via `demoUrl` YAML frontmatter - `usage/` - playgrounds that can be created by running `npm run playground:new` [(docs)](_templates/README.md#new-playground-template) - `versioned_docs/` - versions of the docs created by the docusaurus versioning command @@ -121,22 +192,81 @@ Ionic's documentation is built using [Docusaurus](https://docusaurus.io/). The c The content of the Ionic docs is written as [Markdown](https://commonmark.org/) in `docs/`. Each Markdown file corresponds to a route unless explicitly changed in the frontmatter. ``` -/docs/ => src/pages/index.md -/docs/intro/cli => src/pages/intro/cli.md -/docs/theming/advanced => src/pages/theming/advanced.md -/docs/theming => src/pages/theming.md +/docs => docs/index.mdx +/docs/intro/cli => docs/intro/cli.mdx +/docs/theming/basics => docs/theming/basics.mdx +/docs/v8/intro/cli => versioned_docs/version-v8/intro/cli.mdx +``` + +`/docs` maps to `docs/index.mdx` through `slug: /` in its frontmatter. Older versions live in `versioned_docs/` and are served under their version, such as `/docs/v8/`. + +Versions listed in [`versions.json`](versions.json) are actively maintained. If your change also applies to one of them, make the same change in its `versioned_docs/version-Accordions provide collapsible sections in your content to reduce vertical space while providing a way of organizing and grouping information.
-Action Sheets display a set of options with the ability to confirm or cancel an action.
-Alerts are a great way to offer the user the ability to choose a specific action or list of actions.
-Badges are a small component that typically communicate a numerical value to the user.
-Breadcrumbs are navigation items that are used to indicate where a user is on an app.
-Buttons let your users take action. They're an essential way to interact with and navigate through an app.
-- Cards are a great way to display an important piece of content, and can contain images, buttons, text, and more. -
-Checkboxes can be used to let the user know they need to make a binary decision.
-Chips are a compact way to display data or actions.
-Content is the quintessential way to interact with and navigate through an app.
-Date & time pickers are used to present an interface that makes it easy for users to select dates and times.
-Floating action buttons are circular buttons that perform a primary action on a screen.
-The grid is a powerful mobile-first system for building custom layouts.
-Beautifully designed icons for use in web, iOS, and Android apps.
-Infinite scroll allows you to load new data as the user scrolls through your app.
-Inputs provides a way for users to enter data in your app.
-- Items are elements that can contain text, icons, avatars, images, inputs, and any other native or custom elements. - Items can be swiped, deleted, reordered, edited, and more. -
-Lists can display rows of information, such as a contact list, playlist, or menu.
-- A collection of media components, including avatars, icons, images, and thumbnails, designed to enhance visual - content. -
-Menus are a common navigation pattern. They can be permanently on-screen, or revealed when needed.
-Modals slide in and off screen to display a temporary UI and are often used for login or sign-up pages.
-Navigation is how users move between different pages in your app.
-Popover provides an easy way to present information or options without changing contexts.
-Progress indicators visualize the progression of an operation or activity.
-Radio inputs allow you to present a set of exclusive options.
-Range sliders let users select a value by dragging a knob along a track.
-Refresher provides pull-to-refresh functionality on a content component.
-Reorder lets users drag and drop to reorder a list of items.
-Routing allows navigation based on the current path.
-Searchbar is used to search or filter items, usually from a toolbar.
-Segments provide a set of exclusive buttons that can be used as a filter or view switcher.
-Select is similar to the native HTML select, with a few improvements to sorting and selecting.
-Tabs enable tabbed navigation, a standard navigation pattern in modern apps.
-Toasts are subtle notifications that appear over your app's content without interrupting user interaction.
-Toggles are an input for binary options, often used for options and switches.
-Toolbars are used to house information and actions relating to your app.
-Text is used to style or change the color of text within an application.
-Accordions provide collapsible sections in your content to reduce vertical space while providing a way of organizing and grouping information.
+Action Sheets display a set of options with the ability to confirm or cancel an action.
+Alerts are a great way to offer the user the ability to choose a specific action or list of actions.
+Badges are a small component that typically communicate a numerical value to the user.
+Breadcrumbs are navigation items that are used to indicate where a user is on an app.
+Buttons let your users take action. They're an essential way to interact with and navigate through an app.
+Checkboxes can be used to let the user know they need to make a binary decision.
+Chips are a compact way to display data or actions.
+Content is the quintessential way to interact with and navigate through an app.
+Date & time pickers are used to present an interface that makes it easy for users to select dates and times.
+Floating action buttons are circular buttons that perform a primary action on a screen.
+The grid is a powerful mobile-first system for building custom layouts.
+Beautifully designed icons for use in web, iOS, and Android apps.
+Infinite scroll allows you to load new data as the user scrolls through your app.
+Inputs provide a way for users to enter data in your app.
+Lists can display rows of information, such as a contact list, playlist, or menu.
+Menus are a common navigation pattern. They can be permanently on-screen, or revealed when needed.
+Modals slide in and off screen to display a temporary UI and are often used for login or sign-up pages.
+Navigation is how users move between different pages in your app.
+Popover provides an easy way to present information or options without changing contexts.
+Progress indicators visualize the progression of an operation or activity.
+Radio inputs allow you to present a set of exclusive options.
+Range sliders let users select a value by dragging a knob along a track.
+Refresher provides pull-to-refresh functionality on a content component.
+Reorder lets users drag and drop to reorder a list of items.
+Routing allows navigation based on the current path.
+Searchbar is used to search or filter items, usually from a toolbar.
+Segments provide a set of exclusive buttons that can be used as a filter or view switcher.
+Select is similar to the native HTML select, with a few improvements to sorting and selecting.
+Tabs enable tabbed navigation, a standard navigation pattern in modern apps.
+Toasts are subtle notifications that appear over your app's content without interrupting user interaction.
+Toggles are an input for binary options, often used for options and switches.
+Toolbars are used to house information and actions relating to your app.
+Text is used to style or change the color of text within an application.
+