diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index 1a0efc743b7..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/workflows/CI.yml b/.github/workflows/CI.yml new file mode 100644 index 00000000000..d35a183f9ac --- /dev/null +++ b/.github/workflows/CI.yml @@ -0,0 +1,27 @@ +# GitHub Actions docs +# https://help.github.com/en/articles/about-github-actions +# https://help.github.com/en/articles/workflow-syntax-for-github-actions + +name: Install Dependencies, Lint + +on: [pull_request] + +jobs: + test: + name: Test on node ${{ matrix.node_version }} and ${{ matrix.os }} + runs-on: ${{ matrix.os }} + strategy: + matrix: + node_version: [16] + os: [windows-latest, macOS-latest] + + steps: + - uses: actions/checkout@v1 + - name: Use Node.js ${{ matrix.node_version }} + uses: actions/setup-node@v1 + with: + node-version: ${{ matrix.node_version }} + - name: Install Dependencies + run: npm ci --legacy-peer-deps + - name: Lint + run: npm run lint diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml deleted file mode 100644 index 1cbe5c24b48..00000000000 --- a/.github/workflows/ci.yml +++ /dev/null @@ -1,23 +0,0 @@ -name: CI - -on: - push: - branches: - - '**' - -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/setup-node@v1 - with: - node-version: 12.x - - uses: actions/checkout@v1 - - name: npm install, build, and test - env: - CI: true - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - npm install - npm run lint - npm run build.ci diff --git a/.gitignore b/.gitignore index b94a5eafd6e..71e2c8eba4d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,13 +1,24 @@ +# Dependencies +/node_modules + +# Production +/build + +# Generated files +.docusaurus +.cache-loader +src/components/page/reference/ReleaseNotes/release-notes.json + +# Misc .DS_Store -node_modules/ -.stencil/ -.nova/ -dist/ -www/ -src/pages/**/*.json -src/l10n/pages/**/*.json -src/components/menu/data/ -src/components/page/data/ -src/components/search/data/ -.idea -/.env +.env.local +.env.development.local +.env.test.local +.env.production.local +.env + +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +static/**/node_modules/ diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 00000000000..c9e0e72442c --- /dev/null +++ b/.prettierignore @@ -0,0 +1,15 @@ +src/theme/DocItem +src/theme/DocPage +legacy-stencil-components +scripts/bak + +docs/api +docs/native +docs/cli/commands + +static/code/stackblitz + +.docusaurus +.github +build +node_modules diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 48461475332..a6470cae5f7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,15 +7,12 @@ Thanks for your interest in contributing to Ionic's documentation! :tada: Check - [Using VS Code on Windows](#using-vs-code-on-windows) - [Project Structure](#project-structure) - [Directories](#directories) - - [Page Templates](#page-templates) - - [Menu Templates](#menu-templates) - [Authoring Content](#authoring-content) - [Authoring Locally](#authoring-locally) - - [Reference Content](#reference-content) - [Translation](#translation) - [Reporting Issues](#reporting-issues) - [Pull Request Guidelines](#pull-request-guidelines) - - [Project Management](#project-management) + - [Deploying](#deploying) - [License](#license) @@ -26,11 +23,11 @@ Thanks for your interest in contributing to Ionic's documentation! :tada: Check In order to run the documentation locally, install the dependencies and run the development server: ```sh -$ npm install +$ npm install --legacy-peer-deps $ npm start ``` -> **Note**: recent versions of npm (5+) and Node.js (10+) are required to run certain scripts. +> **Note**: certain versions of npm (5-8) and Node.js (10-16) are required to run certain scripts. --- @@ -44,50 +41,25 @@ The Ionic docs were originally built in a Mac-based environment, so Mac-focused ## Project Structure -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. - -At a high level, the production documentation works like this: - -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/ - ├── index.json - └── index.md - ``` -2. At runtime, the `docs-page` component receives the current path (e.g. `/docs`) -3. The `docs-page` component fetches and parses the [JSON representation](https://ionicframework.com/docs/pages/index.json) of that page -4. The `docs-page` component renders that data using a [template](https://github.com/ionic-team/ionic-docs/tree/master/src/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. +Ionic's documentation is built using [Docusaurus](https://docusaurus.io/). The content is either written or generated as Markdown. ### Directories -- `scripts/` - build scripts used to generate JSON representations of each page and other data used in the docs +- `scripts/` - build scripts used to generate markdown or json files - `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) - -### Page Templates - -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. - -```tsx -const Template = templates[page.template] || template.default; -return ; -``` - -### Menu Templates - -The [`docs-menu`](https://github.com/ionic-team/ionic-docs/blob/master/src/components/menu/menu.tsx) component is responsible for rendering the side menu. The menu content differs by path and is specified in [per-section templates](https://github.com/ionic-team/ionic-docs/tree/master/src/components/menu/templates). - ---- + - `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 +- `static/` + - `demos/` - self-contained demos, optionally presented by pages via `demoUrl` YAML frontmatter +- `versioned_docs/` - versions of the docs created by the docusaurus versioning command +- `versioned_sidebars/` - versions of the docs sidebars created by the docusaurus versioning command ## Authoring Content -The content of the Ionic docs is written as [Markdown](https://commonmark.org/) in `src/pages`. Each Markdown file corresponds to a route. +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 @@ -98,80 +70,24 @@ The content of the Ionic docs is written as [Markdown](https://commonmark.org/) You can make copy edits to the site by [editing the Markdown files directly on GitHub](https://help.github.com/articles/editing-files-in-another-user-s-repository/). In your pull request, please explain what was missing from or inaccurate about the content. -### Authoring Locally - -To edit or create content locally, you'll need to [run the development server](#development-workflow). By default, the pages are only built once while starting the server. You can rebuild the pages continuously as you edit them by concurrently running the `watch-pages` script: - -```sh -$ npm run watch-pages -``` - -> **Note**: the `watch-pages` script won't reload the page. You will need to reload the page manually after your page is rebuilt. - ### Reference Content -The Markdown in `src/pages` does not contain all of the Ionic documentation's content: +The Markdown in `docs/` does not only contain manually written markdown files: - Paths matching `/docs/api/*` are built from the [Ionic Framework](https://github.com/ionic-team/ionic) source code - Paths matching `/docs/native/*` are built from the [Ionic Native](https://github.com/ionic-team/ionic-native) source code - Paths matching `/docs/cli/commands/*` are built from the [Ionic CLI](https://github.com/ionic-team/ionic-cli) source code -#### Updating Ionic Native Community Plugins - -To add or update an Ionic Native [community plugin](/docs/native/community): -1) Open a pull request on the [Ionic Native](https://github.com/ionic-team/ionic-native) repository (both code or documentation). -2) Once the change has been approved and merged into master by the Ionic team, do the following steps: - -```shell -# Clone Ionic Native repo -git clone git@github.com:ionic-team/ionic-native.git -cd ionic-native - -# Build the Ionic Native project -npm run build - -# Run scripts to generate the plugin JSON file -npm ci -npm run docs-json - -# Overwrite the ionic-docs native.json file with the new changes -mv scripts/docs-json/plugins.json /path/to/docs/scripts/data/native.json -``` - -3) Open a PR in the `ionic-docs` repo, submitting the new `native.json` file. - ---- - ## Translation The Ionic docs have been translated into Japanese and are in the process of being translated into Chinese, French, Portuguese, and Spanish. We've chosen these languages because we believe they have the greatest number of developers where English-only documentation would be a barrier. We use Crowdin for our translation service. You can participate in the translation effort on the [Ionic Crowdin page](https://crowdin.com/project/ionic-docs). -_Please submit translation issues to the Crowdin page and not the Ionic Docs GitHub repo_ +_Please submit translation issues to the Crowdin page and not the Ionic Docs GitHub repo._ The Japanese translation of the docs were built by an independent team, lead by [rdlabo](https://github.com/rdlabo) and can be found and contributed to on the [ionic-jp group's `ionic-docs` project page](https://github.com/ionic-jp/ionic-docs). -### Add new pages / Updating sidebar menus - -When adding new pages to the docs, add a new token representing the page name to the appropriate Menu template (`src/components/menu/templates`). - -For example, in `src/components/menu/templates/main.tsx`: - -```javascript -// 'token': 'path' -'menu-intro-cli': '/docs/intro/cli', -``` - -Then, add the token and its translation to each file within the `src/assets/locales` folder: - -For example, in `src/assets/locales/en/messages.json`: - -```javascript -// 'token': 'translated text' -"menu-intro-cli": "CLI Installation", -``` - ## Reporting Issues Before submitting an issue to the Ionic docs repo, please search [existing issues](https://github.com/ionic-team/ionic-docs/issues) to avoid duplicate reports. @@ -191,11 +107,9 @@ If the issue you're reporting is a bug, please be sure it is an issue with the I When submitting pull requests, please keep the scope of your change contained to a single feature or bug. When in doubt, err on the side of smaller pull requests. If your pull request is a new feature, we would recommend opening an issue first to come to an agreement about the feature before putting in significant time. -> **Note**: `tslint` will run automatically when you attempt to commit. Our lint rules extend [tslint-ionic-rules](https://github.com/ionic-team/tslint-ionic-rules). - --- -## Project Management + ## Deploying -The Ionic documentation's `master` branch is deployed automatically and separately from the [Ionic site](https://github.com/ionic-team/ionic-site) itself. The Ionic site then uses a proxy for paths under `/docs` to request the deployed documentation. +The Ionic documentation's `main` branch is deployed automatically and separately from the [Ionic site](https://github.com/ionic-team/ionic-site) itself. The Ionic site then uses a proxy for paths under `/docs` to request the deployed documentation. --- diff --git a/Procfile b/Procfile deleted file mode 100644 index f5ab70b6153..00000000000 --- a/Procfile +++ /dev/null @@ -1,2 +0,0 @@ -release: test -z "$CF_TOKEN" || curl -fsS -X POST "https://api.cloudflare.com/client/v4/zones/$CF_ZONE/purge_cache" -H "Authorization: Bearer $CF_TOKEN" -H "Content-Type: application/json" --data '{"purge_everything": true}' -web: node server.js diff --git a/README.md b/README.md index b9989e6131a..a82f4da1ca6 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # Ionic Docs -The official [Ionic](https://ionicframework.com) documentation, built with [Stencil](https://stenciljs.com). +The official [Ionic](https://ionicframework.com) documentation, built with [Docusaurus](https://docusaurus.io/). [![Crowdin](https://badges.crowdin.net/ionic-docs/localized.svg)](https://crowdin.com/project/ionic-docs) --- -- [Contributing Guide](https://github.com/ionic-team/ionic-docs/blob/master/CONTRIBUTING.md) :flashlight: -- [Project Board](https://github.com/ionic-team/ionic-docs/projects/3) :pushpin: +- [Contributing Guide](./CONTRIBUTING.md) :flashlight: + diff --git a/app.json b/app.json deleted file mode 100644 index 0ee7edb7c04..00000000000 --- a/app.json +++ /dev/null @@ -1,36 +0,0 @@ -{ - "addons": [ - "papertrail" - ], - "buildpacks": [ - { - "url": "heroku/nodejs" - } - ], - "env": { - "NODE_ENV": { - "required": true - }, - "NODEMODULESCACHE": { - "required": true - }, - "NPM_CONFIG_PRODUCTION": { - "required": true - }, - "PORT": { - "required": true - }, - "PROD": { - "required": true - } - }, - "formation": { - "web": { - "quantity": 1 - } - }, - "name": "ionic-docs", - "scripts": { - }, - "stack": "heroku-18" -} diff --git a/babel.config.js b/babel.config.js new file mode 100644 index 00000000000..e00595dae7d --- /dev/null +++ b/babel.config.js @@ -0,0 +1,3 @@ +module.exports = { + presets: [require.resolve('@docusaurus/core/lib/babel/preset')], +}; diff --git a/crowdin.yml b/crowdin.yml index e9458e9a524..c237cf6e3bd 100644 --- a/crowdin.yml +++ b/crowdin.yml @@ -1,7 +1,12 @@ +project_id: '359747' +api_token_env: 'CROWDIN_PERSONAL_TOKEN' +preserve_hierarchy: true + files: - - source: /src/assets/locales/en/messages.json - translation: /src/assets/locales/%two_letters_code%/messages.json - - source: /src/pages/**/*.md - translation: /src/pages/%two_letters_code%/**/%original_file_name% + - source: /i18n/en/**/* + translation: /i18n/%two_letters_code%/**/%original_file_name% + - source: /docs/**/* + translation: /i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name% ignore: - - /src/pages/%two_letters_code%/**/%original_file_name% + - /docs/cli/commands/**/* + - /docs/native/**/* diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000000..2da29748116 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,17 @@ +# Docs folder + +The `/docs` folder houses all markdown files. The page structure loosely maps to the routing on the site since paths can be changed in the frontmatter. + +## Versioning + +This folder can also contain components, assets, and whatever else is meant to be versioned when the docusaurus versioning script is run. For example, if there is a page component that is only relevant to the `layout` section in the current version of Ionic, it could be added to a `_components/` folder in `docs/layout/`. When the versioning script is run, the component will be copied to `versioned_docs/verion-{X}/layout/_components/` and there will now be a separate component in `docs/layout/_components/` that can be deleted or updated to the latest version. The same concept applies to images and other files. + +If components are meant to be shared across versions, they can be put in `src/components/`. If images and other served files are meant to be shared across versions they can be put in `static/`. + +## Auto Generated Files + +All markdown files in these directories are generated from [scripts](/scripts): + +- `docs/api/` +- `docs/cli/commands/` +- `docs/native/` diff --git a/docs/angular/lifecycle.md b/docs/angular/lifecycle.md new file mode 100644 index 00000000000..ddb7b902fbb --- /dev/null +++ b/docs/angular/lifecycle.md @@ -0,0 +1,103 @@ +--- +title: Ionic Page Life Cycle +sidebar_label: Lifecycle +--- + +
+Learn the fundamentals you need to know to start building amazing apps with Ionic Framework.
+Learn the basics of navigation inside your app with Ionic and Angular Router
+Learn about using Ionic lifecycle events in class components and with hooks
+aria-hidden="true"
. This will not visually hide the icon, but it will hide the element from assistive technology.
+
+```html
+
+```
+
+
+If the icon is interactive, it should have alternate text defined by adding an aria-label
.
+
+```html
+aria-label
added to it, and the icon should be hidden using aria-hidden
.
+
+```html
+