diff --git a/.eslintrc.json b/.eslintrc.json new file mode 100644 index 00000000000..c4a8fee5514 --- /dev/null +++ b/.eslintrc.json @@ -0,0 +1,22 @@ +{ + "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"], + "parser": "@typescript-eslint/parser", + "parserOptions": { + "ecmaVersion": 2018, + "sourceType": "module", + "ecmaFeatures": { + "jsx": true + } + }, + "plugins": ["@typescript-eslint"], + "rules": { + "@typescript-eslint/ban-types": "off", + "@typescript-eslint/explicit-module-boundary-types": "off", + "@typescript-eslint/no-explicit-any": "off", + "@typescript-eslint/no-non-null-assertion": "off", + "@typescript-eslint/no-unused-vars": "off", + "no-prototype-builtins": "off", + "no-useless-escape": "off", + "prefer-spread": "off" + } +} diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000000..b1f04ad75d3 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,14 @@ +# Lines starting with '#' are comments. +# Each line is a file pattern followed by one or more owners. + +# More details are here: https://help.github.com/articles/about-codeowners/ + +# The '*' pattern is global owners. + +# Order is important. The last matching pattern has the most precedence. +# The folders are ordered as follows: + +# In each subsection folders are ordered first by depth, then alphabetically. +# This should make it easy to add new rules without breaking existing ones. + +* @ionic-team/framework diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index 248d7fb9b3e..00000000000 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -name: Bug report -about: Report a bug on the docs site -title: '' -labels: bug -assignees: '' - ---- - -**Describe the bug** -A clear and concise description of what the bug is. - -**To Reproduce** -Steps to reproduce the behavior: -1. Go to '...' -2. Click on '....' -3. Scroll down to '....' -4. See error - -**Expected behavior** -A clear and concise description of what you expected to happen. - -**Screenshots** -If applicable, add screenshots to help explain your problem. - -**Browser and OS (please complete the following information):** - - OS: [e.g. iOS] - - Browser [e.g. chrome, safari] - - Version [e.g. 22] - -**Additional context** -Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 00000000000..3cae620736e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,43 @@ +name: 🐛 Bug Report +description: Report a bug on the docs site +labels: ["triage"] +title: "bug: " +body: + - type: textarea + attributes: + label: Describe the Bug + description: A clear description of what the bug is and how it manifests. + validations: + required: true + - type: textarea + attributes: + label: Expected Behavior + description: A clear description of what you expected to happen. + validations: + required: true + - type: textarea + attributes: + label: Steps to Reproduce + description: Please explain the steps required to duplicate this issue. + validations: + required: true + - type: textarea + attributes: + label: Screenshots + description: If applicable, add screenshots to help explain the problem. + - type: input + attributes: + label: Operating System + description: The operating system you are running (e.g. Windows) + - type: input + attributes: + label: Browser + description: The browser you are running (e.g. Chrome, Safari) + - type: input + attributes: + label: Version + description: The browser version you are running (e.g. 14) + - type: textarea + attributes: + label: Additional Information + description: List any other information that is relevant to your issue. diff --git a/.github/ISSUE_TEMPLATE/content-issue.md b/.github/ISSUE_TEMPLATE/content-issue.md deleted file mode 100644 index 58b864b751c..00000000000 --- a/.github/ISSUE_TEMPLATE/content-issue.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -name: Content issue -about: Report missing or inaccurate content on the docs -title: '' -labels: content -assignees: '' - ---- - -**URL** -The URL at which the content is missing or inaccurate - -**What is missing or inaccurate about the content on this page?** diff --git a/.github/ISSUE_TEMPLATE/content-issue.yml b/.github/ISSUE_TEMPLATE/content-issue.yml new file mode 100644 index 00000000000..404492e1736 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/content-issue.yml @@ -0,0 +1,17 @@ +name: 📕 Content Issue +description: Report missing or inaccurate content on the docs +labels: ["triage"] +title: "content: " +body: + - type: input + attributes: + label: URL + description: The URL at which the content is missing or inaccurate + validations: + required: true + - type: textarea + attributes: + label: Issue Description + description: What is missing or inaccurate about the content on this page? + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md deleted file mode 100644 index d513e5c0428..00000000000 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -name: Feature request -about: Suggest a feature for the docs -title: '' -labels: feature -assignees: '' - ---- - -**Is your feature request related to a problem? Please describe.** -A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] - -**Describe the solution you'd like** -A clear and concise description of what you want to happen. - -**Describe alternatives you've considered** -A clear and concise description of any alternative solutions or features you've considered. - -**Additional context** -Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 00000000000..5a964579982 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,23 @@ +name: 💡 Feature Request +description: Suggest a feature for the docs +labels: ["triage"] +title: "feat: " +body: + - type: textarea + attributes: + label: Describe Problem + description: A clear and concise description of what the problem is. Ex. I am always frustrated when [...] + validations: + required: true + - type: textarea + attributes: + label: Describe Preferred Solution + description: A clear and concise description of what you want to happen. + - type: textarea + attributes: + label: Describe Alternatives + description: A clear and concise description of any alternative solutions or features you have considered. + - type: textarea + attributes: + label: Additional Information + description: Add any other context or screenshots about the feature request here. \ No newline at end of file diff --git a/.github/ionic-issue-bot.yml b/.github/ionic-issue-bot.yml new file mode 100644 index 00000000000..f0da0d54073 --- /dev/null +++ b/.github/ionic-issue-bot.yml @@ -0,0 +1,86 @@ +triage: + label: triage + dryRun: false + +closeAndLock: + labels: + - label: 'ionitron: support' + message: > + Thanks for the issue! This issue appears to be a support request. We use this issue tracker exclusively for + content issues, bug reports and feature requests related to the documentation. Please use our + [forum](https://forum.ionicframework.com/) for help or questions about Ionic Framework. + + + Thank you for using Ionic! + - label: 'ionitron: missing template' + message: > + Thanks for the issue! It appears that you have not filled out the provided issue template. We use this issue + template in order to gather more information and further assist you. Please create a new issue and ensure the + template is fully filled out. + + + Thank you for using Ionic! + close: true + lock: true + dryRun: false + +comment: + labels: + - label: "help wanted" + message: > + This issue has been labeled as `help wanted`. This label is added to issues + that we believe would be good for contributors. + + + If you'd like to work on this issue, please comment here letting us know that + you would like to submit a pull request for it. This helps us to keep track of + the pull request and make sure there isn't duplicated effort. + + + For a guide on how to create a pull request and test this project locally to see + your changes, see our [contributing documentation](https://github.com/ionic-team/ionic-docs/blob/main/CONTRIBUTING.md). + + + Thank you! + - label: 'ionitron: needs reproduction' + message: > + Thanks for the issue! This issue has been labeled as `needs reproduction`. This label is added to issues that + we are not able to reproduce. + + + Please provide easy to follow steps for us to reproduce this issue. + dryRun: false + +noReply: + days: 14 + maxIssuesPerRun: 100 + label: "needs: reply" + responseLabel: triage + exemptProjects: true + exemptMilestones: true + message: > + Thanks for the issue! This issue is being closed due to the lack of a reply. If this is still an issue, + please create a new issue and ensure the template is fully filled out. + + + Thank you for using Ionic! + close: true + lock: true + dryRun: false + +noReproduction: + days: 14 + maxIssuesPerRun: 100 + label: "ionitron: needs reproduction" + responseLabel: triage + exemptProjects: true + exemptMilestones: true + message: > + Thanks for the issue! This issue is being closed due to the lack of a reproduction. If this is still an issue, + please create a new issue and ensure the template is fully filled out. + + + Thank you for using Ionic! + close: true + lock: true + dryRun: false diff --git a/.github/main.workflow b/.github/main.workflow deleted file mode 100644 index 0ec379079f8..00000000000 --- a/.github/main.workflow +++ /dev/null @@ -1,22 +0,0 @@ -workflow "Build and Test" { - on = "push" - resolves = ["Build"] -} - -action "Install" { - uses = "actions/npm@de7a3705a9510ee12702e124482fad6af249991b" - args = "install" -} - -action "Lint" { - uses = "actions/npm@de7a3705a9510ee12702e124482fad6af249991b" - needs = ["Install"] - args = "run lint" -} - -action "Build" { - uses = "actions/npm@de7a3705a9510ee12702e124482fad6af249991b" - needs = ["Lint"] - args = "run build.ci" - secrets = ["GITHUB_TOKEN"] -} diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml new file mode 100644 index 00000000000..66c35d1a18e --- /dev/null +++ b/.github/workflows/CI.yml @@ -0,0 +1,42 @@ +# GitHub Actions docs +# https://help.github.com/en/articles/about-github-actions +# https://help.github.com/en/articles/workflow-syntax-for-github-actions + +name: Validate Docs + +on: [pull_request] + +jobs: + test: + name: Test on ${{ matrix.os }} + runs-on: ${{ matrix.os }} + strategy: + matrix: + node_version: [20] + # Build processes work differently across operating systems, so the + # checks run on each one to make sure anyone can contribute to the + # docs. + os: [windows-latest, macOS-latest] + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - name: ⚙️ Use Node.js ${{ matrix.node_version }} + uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 + with: + node-version: ${{ matrix.node_version }} + - name: 🕸️ Install Dependencies + run: npm ci --legacy-peer-deps + - name: 🖌️ Lint + run: npm run lint + - name: Test + run: npm run test + - name: 🔤 Spell Check + run: npm run spellcheck + - uses: ./.github/workflows/actions/check-translations + # Lint and spell check changes should be pushed + # to the branch before the branch is merge eligible. + # + # The translation keys check should not produce any changes. + - name: 🔍 Check Diff + run: git diff --exit-code + shell: bash diff --git a/.github/workflows/actions/check-translations/action.yml b/.github/workflows/actions/check-translations/action.yml new file mode 100644 index 00000000000..3e53a643597 --- /dev/null +++ b/.github/workflows/actions/check-translations/action.yml @@ -0,0 +1,20 @@ +name: 'Check Translations' +description: 'Validates the translated locales without building them' +runs: + using: 'composite' + steps: + # Surfaces failures unique to a translated locale, such as duplicate + # translation keys, while the changes are still in review. Previews only + # build the default locale, so translated locale issues would not surface + # until after merging into main. + # + # The sidebars reference the native and CLI docs, which are generated rather + # than committed, so those have to exist before the translations can be + # extracted. + - name: 🇯🇵 Extract Translations + shell: bash + run: | + trap 'rm -rf i18n' EXIT + node scripts/native.mjs + node scripts/cli.mjs + npx docusaurus write-translations --locale ja diff --git a/.gitignore b/.gitignore index 539d68d27da..a1ae05b6ea1 100644 --- a/.gitignore +++ b/.gitignore @@ -1,12 +1,25 @@ +# Dependencies +/node_modules + +# Production +/build + +# Generated files +.docusaurus +.cache-loader +src/components/page/reference/ReleaseNotes/release-notes.json + +# Misc .DS_Store -node_modules/ -.stencil/ -dist/ -www/ -src/pages/**/*.json -src/l10n/pages/**/*.json -src/components/menu/data/ -src/components/page/data/ -src/components/search/data/ +.env.local +.env.development.local +.env.test.local +.env.production.local +.env + +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +static/**/node_modules/ .idea -/.env diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 00000000000..859390e3ab1 --- /dev/null +++ b/.prettierignore @@ -0,0 +1,35 @@ +# Ejected components keep upstream's formatting so they stay diffable against +# @docusaurus/theme-classic. Refer to `src/theme/README.md`. +# Wrapped components are our own code, so they follow the repo's formatting. +src/theme/DocItem/Layout/index.tsx +src/theme/EditMetaRow/index.tsx +src/theme/Icon/Edit/index.tsx +src/theme/Icon/Language/index.tsx +src/theme/Layout/index.tsx +src/theme/NavbarItem/LocaleDropdownNavbarItem/index.tsx +src/theme/prism-include-languages.ts + +legacy-stencil-components +scripts/bak + +docs/api +docs/native +versioned_docs/version-v*/native +docs/cli/commands +# Each definition in these files is one line of prose inside a JSX
. +# Prettier's mdx parser reflows those children and moves link text onto its own +# line, which MDX then wraps in a paragraph, rendering invalid HTML such as +#

Android SDK

. Formatting these files reintroduces that markup. +docs/reference/glossary.md +versioned_docs/version-v*/reference/glossary.md + +# Archived versions +versioned_docs/version-v5 +versioned_docs/version-v6 + +static/code/stackblitz + +.docusaurus +.github +build +node_modules diff --git a/.vscode/launch.json b/.vscode/launch.json index 593c0150124..e50b8ef32ea 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -11,6 +11,7 @@ "args": [ "${workspaceFolder}/node_modules/.bin/stencil", "build", + "--debug", "--prerender", "--max-workers=1" ], diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 094d7e86f4a..534db3dd80a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,112 +2,187 @@ Thanks for your interest in contributing to Ionic's documentation! :tada: Check the guidelines below for suggestions and requirements before submitting your contribution. + + TABLE OF CONTENTS + + - [Development Workflow](#development-workflow) + - [Previewing Changes](#previewing-changes) + - [Linting Documentation](#linting-documentation) + - [Spell Check](#spell-check) +- [Using VS Code on Windows](#using-vs-code-on-windows) - [Project Structure](#project-structure) + - [Directories](#directories) - [Authoring Content](#authoring-content) + - [Reference Content](#reference-content) - [Translation](#translation) - [Reporting Issues](#reporting-issues) - [Pull Request Guidelines](#pull-request-guidelines) -- [Project Management](#project-management) +- [Deploying](#deploying) + - [Archiving a Version](#archiving-a-version) +- [License](#license) --- ## Development Workflow +### Previewing Changes + In order to run the documentation locally, install the dependencies and run the development server: ```sh -$ npm install -$ npm start +npm install +npm start ``` -> **Note**: recent versions of npm (5+) and Node.js (8+) are required to run certain scripts. +#### GitHub Token ---- +The documentation build requires a GitHub Personal Access Token to fetch Ionic Framework release notes. The build will still work locally without it (release notes will be empty), but it's required for Vercel preview and production builds. -## Project Structure +**Local Development:** -Ionic's documentation is built using [Stencil](https://stenciljs.com). The content is written as Markdown or pulled in as JSON data from other Ionic repositories. +1. Create a [fine-grained Personal Access Token](https://github.com/settings/personal-access-tokens/new) with: -At a high level, the production documentation works like this: + - **Repository access**: Public repositories (read-only) + - **Expiration**: 366 days (update annually) -1. At build time, the `build-pages` script reads the Markdown in `src/pages/` and creates a JSON representation of each page at the same path - ``` - pages/ - ├── intro.json - └── intro.md +2. Add the token to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.): + + ```sh + export GITHUB_TOKEN=github_pat_... ``` -2. At runtime, the `docs-page` component receives the current path (e.g. `/docs/intro`) -3. The `docs-page` component fetches and parses the [JSON representation](https://ionicframework.com/docs/pages/intro.json) of that page -4. The `docs-page` component renders that data using a [template](/components/page/templates) -> **Note**: most reference content (e.g. APIs, native plugins, CLI commands) is not stored as Markdown. Those pages are created using data provided by other repositories to the `build-pages` script. +3. Reload your shell or run `source ~/.zshrc` (or equivalent) -### Directories +**Vercel:** -- `scripts/` - build scripts used to generate JSON representations of each page and other data used in the docs -- `src/` - source code and content of the docs - - `assets/` - static assets used on the site, like images and fonts - - `components/` - Stencil components used in the documentation UI - - `demos/` - Self-contained demos, optionally presented by pages via `demoUrl` YAML frontmatter - - `pages/` - Markdown content organized by route and uncommitted JSON representation of each page - - `styles/` - Global and page-specific styles (non-component styles) +1. Create a [fine-grained Personal Access Token](https://github.com/settings/personal-access-tokens/new) with the same settings as above, but with: -### Page Templates + - **Owner**: ionic-team organization (not your personal account) -The [`docs-page`](https://github.com/ionic-team/ionic-docs/blob/master/src/components/page/page.tsx) component is responsible for loading and rendering page content. Page content is rendered using one of the templates exported [here](https://github.com/ionic-team/ionic-docs/blob/master/src/components/page/templates/index.ts). Pages can specify a template via the `template` key in their frontmatter, or the default template will be used. +2. Add the token to Vercel project settings: -```tsx -const Template = templates[page.template] || template.default; -return