Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
340 lines (230 loc) · 16.3 KB

CONTRIBUTING.md

File metadata and controls

340 lines (230 loc) · 16.3 KB
Raw

Contributing Guide

Thanks for your interest in contributing to Ionic's documentation! 🎉 Check the guidelines below for suggestions and requirements before submitting your contribution.

TABLE OF CONTENTS

Development Workflow

Previewing Changes

In order to run the documentation locally, install the dependencies and run the development server:

npm install
npm start

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.

Local Development:

  1. Create a fine-grained Personal Access Token with:

    • Repository access: Public repositories (read-only)
    • Expiration: 366 days (update annually)

  2. Add the token to your shell profile (~/.zshrc, ~/.bashrc, etc.):

    export GITHUB_TOKEN=github_pat_...

  3. Reload your shell or run source ~/.zshrc (or equivalent)

Vercel:

  1. Create a fine-grained Personal Access Token with the same settings as above, but with:

    • Owner: ionic-team organization (not your personal account)

  2. Add the token to Vercel project settings:

    • Go to your project on Vercel
    • Navigate to Settings → Environment Variables
    • Add GITHUB_TOKEN with the token value
    • Select Production and Preview environments

  3. Redeploy the project for the token to take effect

Without the token, the build will fail with an error message indicating the token is missing.

Linting Documentation

This repository uses Prettier, an opinionated code formatter, in order to keep consistent formatting throughout the documentation. Run the following command to automatically fix all formatting, and then push any changes:

npm run lint

Spell Check

This repository uses cspell, a spell checker for code, to automatically flag any spelling errors. Run the following command to see any spelling errors:

npm run spellcheck

Note

Any spelling errors will need to be fixed manually. There are various ways to ignore words or sections that were flagged erroneously. These are listed below.

Ignoring words

To ignore:

  • A specific word, add it to the following file: cspell-wordlist.txt

    • For example, Ionicons is flagged as an unknown word. Since this is the name of our software, it has been added to this file to be ignored.

  • A directory or anything matching a regular expression, update the following file: cspell.json

    • For example, we don't want to flag anything inside of code ticks (`) or code blocks (```), so there are regular expressions added to ignore anything inside of these.

  • An entire line, add the following comment above it:

    <!-- cspell:disable-next-line -->

  • Multiple lines, add comments above and below the lines to be ignored:

    <!-- cspell:disable -->

<p>Everything inside of these comments will be ignored by the spell checkr. Proofread your own words carefully.</p>

<!-- cspell:enable -->

Important

You need to have line breaks between the cspell comments and any HTML elements, otherwise the build will error with Module build failed.

Tips

Before adding a word or section to be ignored, see if there is a way to make it pass the spell check. Technical terms that are part of an API may need to be wrapped in code formatting. For example, the word keydown is flagged as an unknown word by the spell checker, but this is a Web API event. We can wrap any mentions of keydown in two backticks (`keydown`) in order to avoid it being flagged by the spell checker.

Comments disabling the next line or entire sections of documentation are useful for making the spell checker ignore people's names.

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.

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:

  • 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.
  • If you've already cloned the ionic-docs repo, the files may already be cached as LF. To undo this, you need to clean the cache files of the repository. Run the following (make sure you stage or commit your changes first): git rm --cached -r . then git reset --hard.

Project Structure

Ionic's documentation is built using Docusaurus. The content is either written or generated as Markdown.

Directories

  • scripts/ - build scripts used to generate markdown or json files
  • src/ - source code and content of the docs
    • 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
    • usage/ - playgrounds that can be created by running npm run playground:new (docs)
  • 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 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

You can make copy edits to the site by editing the Markdown files directly on GitHub. In your pull request, please explain what was missing from or inaccurate about the content.

Reference Content

The Markdown in docs/ does not only contain manually written markdown files:

  • Paths matching /docs/api/* are built from the Ionic Framework source code
  • Paths matching /docs/native/* are built from the Ionic Native source code
  • Paths matching /docs/cli/commands/* are built from the Ionic CLI source code

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.

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 and can be found and contributed to on the ionic-jp group's ionic-docs project page.

Reporting Issues

Before submitting an issue to the Ionic docs repo, please search existing issues to avoid duplicate reports.

If the issue you're reporting is a bug, please be sure it is an issue with the Ionic docs themselves and not the subject of the documentation. With your report, please provide:

  • Steps to reproduce
  • Expected behavior
  • OS and browser versions
  • If possible, a demo repo or CodePen/CodeSandbox

Note

Some reference content is pulled from other Ionic repos. In that case, please submit your issue on the docs repo with a link to the repo where the content lives.

Pull Request Guidelines

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.

Deploying

The Ionic documentation's main branch is deployed automatically and separately from the Ionic site itself. The Ionic site then uses a proxy for paths under /docs to request the deployed documentation.

Archiving a Version

Archived versions are served from a frozen Vercel deployment instead of being rebuilt on every main deploy, which keeps build times and memory usage low. That deployment is a full snapshot of the site, so it serves every version that was in the build. Two files control this:

  • versions.json: lists the older versions Docusaurus rebuilds on every deploy. It does not include the current version, which is built from docs/ and takes its label from versions.current in docusaurus.config.js.
  • versionsArchived.json: maps each archived version to the frozen deployment URL the version picker links to.

The docs keep the current version plus one older version rebuildable, so each major release archives one version and involves two different version numbers. The steps below refer to them as:

  • <archiving>: the version being frozen and removed from versions.json.
  • <last-current>: the version that just stopped being current and moved into versions.json. It is not being archived, but step 1 has to account for it.

For example, when v9 becomes current: v8 is <last-current> and v7 is <archiving>.

The archived URL has to point at a build that included <archiving>, so you build it first, then move it to versionsArchived.json:

  1. Check the vercel.json redirects. The frozen deployment bakes in whatever vercel.json looked like at build time, and it serves every version in that build. Any :version(...) group missing a version therefore stays broken on that host for good. Make sure the groups already list <last-current>, which is the one most likely to be missing since it only just moved into versions.json. The angular, react, vue and javascript landing pages each need a group, as no version ships an index page for them:

    {
  "source": "/docs/:version(v6|v7|<last-current>)/angular",
  "destination": "/docs/:version/angular/overview"
},
{
  "source": "/docs/:version(<last-current>)/javascript",
  "destination": "/docs/:version/javascript/overview"
}

    The groups accumulate, so existing entries stay in place whether or not that version is archived and you are only ever adding to them. The javascript group only covers versions that have a javascript/ section.

Everything from here on refers to <archiving>:

  1. Build <archiving>. Make sure it is in versions.json. If you are refreshing an already-archived version, move it out of versionsArchived.json and back into versions.json, and add it back to the generation scripts in step 10. Commit, push and let Vercel deploy.

  2. Promote the deployment. In the Vercel dashboard, open that deployment and Promote to Production so it does not get cleaned up. Wait for the build to finish before pushing again, or it may get canceled.

  3. Copy its URL. Use the deployment's unique ionic-docs-<hash>-ionic1.vercel.app URL, not the branch or production alias.

  4. Archive it. Remove <archiving> from versions.json, then add it to versionsArchived.json with /docs/<archiving> appended and no trailing slash (a trailing slash causes a brief 404 flash):

    versions.json

     [
-  "v8",
-  "<archiving>"
+  "v8"
 ]

    versionsArchived.json

    {
  "<archiving>": "https://ionic-docs-<hash>-ionic1.vercel.app/docs/<archiving>",
  "v6": "https://ionic-docs-lq0if04rc-ionic1.vercel.app/docs/v6",
  "v5": "https://ionic-docs-5utg8ms4c-ionic1.vercel.app/docs/v5"
}

  5. Update .prettierignore. Add the archived version folders to the archived versions group to keep Prettier from formatting generated files:

    static/usage/<archiving>
versioned_docs/version-<archiving>

  6. Update cspell.json. Add the archived version to the ignorePaths array so the spell checker skips generated files:

    "ignorePaths": [
  ...
  "versioned_docs/version-v5",
  "versioned_docs/version-v6",
+ "versioned_docs/version-<archiving>"
]

  7. Update renovate.json. Add the archived version's StackBlitz examples to ignorePaths so Renovate stops opening dependency PRs against frozen examples:

    "ignorePaths": [
  "static/code/stackblitz/v6/**",
+ "static/code/stackblitz/<archiving>/**"
]

    Then remove that version's @ionic/ allowedVersions rule from packageRules, since it no longer has anything to match.

  8. Update the playground generator. Remove <archiving> from the version choices in _templates/playground/new/index.js so npm run playground:new stops offering a version that is no longer built. The choices are bare numbers, without the v:

    -              choices: ['<archiving>', '8', '9'],
+              choices: ['8', '9'],

  9. Update the generation scripts. Remove <archiving> from the write lists in scripts/native.mjs and scripts/cli.mjs, so every build stops regenerating content for a version served from a frozen deployment. The remaining targets are docs/ (the current version) and the one older version still in versions.json.

    scripts/native.mjs

     writeFileSync(`docs/native/${fileName}`, apiContent);
-  writeFileSync(`versioned_docs/version-<archiving>/native/${fileName}`, apiContent);
 writeFileSync(`versioned_docs/version-v8/native/${fileName}`, apiContent);

    scripts/cli.mjs

     writeFileSync(`docs/${path}`, data);
-  writeFileSync(`versioned_docs/version-<archiving>/${path}`, data);
 writeFileSync(`versioned_docs/version-v8/${path}`, data);

  10. Open a PR. Once merged, the version picker links to the archive and main stops building <archiving>.

Removed versions keep their authored versioned_docs/ and versioned_sidebars/ content, so they can be rebuilt anytime by adding them back to versions.json. Their native/ and cli/commands/ pages are generated rather than committed, so a rebuild also needs the version back in the write lists from step 10. Without it those sections build empty.

Note

Ionic v3 and v4 use other build tools and are not managed here.

License

This repo is licensed and managed separately from Ionic itself.

By contributing to this repo, you agree to have your contributions licensed under the Apache 2.0 license. See LICENSE for the full license text.