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