mirror of
https://github.com/ionic-team/ionic-framework.git
synced 2025-08-21 04:53:58 +08:00
b315b0cb29
Start your review here 👉 [docs/README.md](https://github.com/ionic-team/ionic-framework/blob/FW-6107/docs/README.md) ## What is the current behavior? Documentation files with information on how to contribute, component implementations, testing, etc. are scattered throughout various folders in this repository. ## What is the new behavior? Consolidates the documentation files into a root `docs/` directory for easier discovery and organization. `/docs` tree: ``` ├── _config.yml ├── component-guide.md ├── CONTRIBUTING.md ├── README.md ├── sass-guidelines.md ├── angular │ ├── README.md │ └── testing.md ├── core │ ├── README.md │ └── testing │ ├── README.md │ ├── api.md │ ├── best-practices.md │ ├── preview-changes.md │ └── usage-instructions.md ├── react │ ├── README.md │ └── testing.md ├── react-router │ ├── README.md │ └── testing.md ├── vue │ ├── README.md │ └── testing.md └── vue-router ├── README.md └── testing.md ``` **Migrates the following:** | Previous Location | New Location | | ----------------------------------------------------------- | ----------------------------------------- | | `.github/COMPONENT-GUIDE.md` | `docs/component-guide.md` | | `.github/CONTRIBUTING.md` | `docs/CONTRIBUTING.md` | | `core/scripts/README.md` | `docs/core/testing/preview-changes.md` | | `core/src/utils/test/playwright/docs/api.md` | `docs/core/testing/api.md` | | `core/src/utils/test/playwright/docs/best-practices.md` | `docs/core/testing/best-practices.md` | | `core/src/utils/test/playwright/docs/README.md` | `docs/core/testing/README.md` | | `core/src/utils/test/playwright/docs/usage-instructions.md` | `docs/core/testing/usage-instructions.md` | | `packages/angular/test/README.md` | `docs/angular/testing.md` | | `packages/react-router/test/README.md` | `docs/react-router/testing.md` | | `packages/react/test/README.md` | `docs/react/testing.md` | | `packages/react/test/base/README.md` | `docs/react/testing.md` | | `packages/vue/test/README.md` | `docs/vue/testing.md` | **Adds the following:** | File | Description | | ----------------------------- | ----------------------------------------------------------------------- | | `docs/sass-guidelines.md` | Sass Variable guidelines taken from `ionic-framework-design-documents` | | `docs/README.md` | Entry file that should link to all other files | | `docs/_config.yml` | Config file for use with GitHub pages | | `docs/core/README.md` | Description of core, links to contributing and testing | | `docs/angular/README.md` | Description of angular, links to contributing and testing | | `docs/react/README.md` | Description of react, links to contributing and testing | | `docs/react-router/README.md` | Description of react-router, links to contributing and testing | | `docs/vue/README.md` | Description of vue, links to contributing and testing | | `docs/vue-router/README.md` | Description of vue-router, links to contributing and testing | | `docs/vue-router/testing.md` | Testing file for vue-router, populated from vue-router's main README | **Does not** add any files for `angular-server`. This is because the README is essentially empty and there is no testing in that directory. I can add blank files if we want to have something to add to later. **Does not** migrate the content of the packages' root `README.md` files. These files are used for their npm package descriptions so we should not edit them. ## Hosting Documentation We can (and should) host these files using GitHub Pages. I have duplicated them in a personal repository to see how this would look: [docs-consolidation](https://brandyscarney.github.io/docs-consolidation/). Doing so will require some formatting fixes (see [Sass Guidelines](https://brandyscarney.github.io/docs-consolidation/sass-guidelines.html#-reusable-values)) so I did not publish them now but we can easily enable GitHub pages by toggling a setting in this repository. ## Other information - Verify that no documentation files were missed in the migration - You can use these commands to search for `*.md` files in a directory: - `find core/src -type f -name "*.md" -print` - `find packages/angular -type f -name "*.md" -not -path "**/node_modules/*" -print` - I did add some redirect links in some of the existing markdown files so they might still exist for that reason - We should probably break up the contributing + component guide documentation into smaller files, such as including best practices, but I wanted to get everything in the same place first - The contributing has sections on each of the packages that we could move to that package's docs folder: https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md#core --------- Co-authored-by: Maria Hutt <thetaPC@users.noreply.github.com>
107 lines
6.2 KiB
Markdown
107 lines
6.2 KiB
Markdown
<p align="center">
|
|
<a href="#">
|
|
<img alt="Ionic" src="https://github.com/ionic-team/ionic-framework/blob/main/.github/assets/logo.png?raw=true" width="60" />
|
|
</a>
|
|
</p>
|
|
|
|
<h1 align="center">
|
|
Ionic
|
|
</h1>
|
|
|
|
<p align="center">
|
|
Ionic is an open source app development toolkit for building modern, fast, top-quality cross-platform native and Progressive Web Apps from a single codebase with JavaScript and the Web.
|
|
</p>
|
|
<p align="center">
|
|
Ionic is based on <a href="https://www.webcomponents.org/introduction">Web Components</a>, which enables significant performance, usability, and feature improvements alongside support for popular web frameworks like <a href="https://angular.io/">Angular</a>, <a href="https://reactjs.com/">React</a>, and <a href="https://vuejs.org/">Vue</a>.
|
|
|
|
</p>
|
|
|
|
<p align="center">
|
|
<a href="https://github.com/ionic-team/ionic-framework/blob/main/LICENSE">
|
|
<img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Ionic Framework is released under the MIT license." />
|
|
</a>
|
|
<a href="https://github.com/ionic-team/ionic/blob/main/docs/CONTRIBUTING.md">
|
|
<img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs welcome!" />
|
|
</a>
|
|
<a href="https://twitter.com/Ionicframework">
|
|
<img src="https://img.shields.io/twitter/follow/ionicframework.svg?label=Follow%20@IonicFramework" alt="Follow @IonicFramework">
|
|
</a>
|
|
<a href="https://ionic.link/discord">
|
|
<img src="https://img.shields.io/discord/520266681499779082?color=7289DA&label=%23ionic&logo=discord&logoColor=white" alt="Official Ionic Discord" />
|
|
</a>
|
|
</p>
|
|
|
|
<h2 align="center">
|
|
<a href="https://ionicframework.com/docs/intro/cli">Quickstart</a>
|
|
<span> · </span>
|
|
<a href="https://ionicframework.com/docs/">
|
|
Documentation
|
|
</a>
|
|
<span> · </span>
|
|
<a href="https://github.com/ionic-team/ionic/blob/main/docs/CONTRIBUTING.md">Contribute</a>
|
|
<span> · </span>
|
|
<a href="https://blog.ionicframework.com/">Blog</a>
|
|
<br />
|
|
Community:
|
|
<a href="https://ionic.link/discord">Discord</a>
|
|
<span> · </span>
|
|
<a href="https://forum.ionicframework.com/">Forums</a>
|
|
<span> · </span>
|
|
<a href="https://twitter.com/Ionicframework">Twitter</a>
|
|
</h2>
|
|
|
|
### Packages
|
|
|
|
| Project | Package | Version | Downloads| Links |
|
|
| ------- | ------- | ------- | -------- |:-----:|
|
|
| **Core** | [`@ionic/core`](https://www.npmjs.com/package/@ionic/core) | [](https://www.npmjs.com/package/@ionic/core) | <a href="https://www.npmjs.com/package/@ionic/core" target="_blank"><img src="https://img.shields.io/npm/dm/@ionic/core.svg" alt="NPM Downloads" /></a> | [`README.md`](core/README.md)
|
|
| **Angular** | [`@ionic/angular`](https://www.npmjs.com/package/@ionic/angular) | [](https://www.npmjs.com/package/@ionic/angular) | <a href="https://www.npmjs.com/package/@ionic/angular" target="_blank"><img src="https://img.shields.io/npm/dm/@ionic/angular.svg" alt="NPM Downloads" /></a> | [`README.md`](packages/angular/README.md)
|
|
| **Vue** | [`@ionic/vue`](https://www.npmjs.com/package/@ionic/vue) | [](https://www.npmjs.com/package/@ionic/vue) | <a href="https://www.npmjs.com/package/@ionic/vue" target="_blank"><img src="https://img.shields.io/npm/dm/@ionic/vue.svg" alt="NPM Downloads" /></a> | [`README.md`](packages/vue/README.md)
|
|
| **React** | [`@ionic/react`](https://www.npmjs.com/package/@ionic/react) | [](https://www.npmjs.com/package/@ionic/react) | <a href="https://www.npmjs.com/package/@ionic/react" target="_blank"><img src="https://img.shields.io/npm/dm/@ionic/react.svg" alt="NPM Downloads" /></a> |[`README.md`](packages/react/README.md)
|
|
|
|
Looking for the `ionic-angular` package? Ionic 3 has been moved to the [`ionic-v3`](https://github.com/ionic-team/ionic-v3) repo. See [Earlier Versions](#earlier-versions).
|
|
|
|
### Getting Started
|
|
|
|
Start a new project by following our quick [Getting Started guide](https://ionicframework.com/getting-started/).
|
|
We would love to hear from you! If you have any feedback or run into issues using our framework, please file
|
|
an [issue](https://github.com/ionic-team/ionic/issues/new) on this repository.
|
|
|
|
### Migration Guides
|
|
|
|
Already have an Ionic app? These guides will help you migrate to the latest versions.
|
|
|
|
* [Migrate from v6 to v7](https://ionicframework.com/docs/updating/7-0)
|
|
* [Migrate from v5 to v6](https://ionicframework.com/docs/updating/6-0)
|
|
* [Migrate from v4 to v5](https://ionicframework.com/docs/updating/5-0)
|
|
* [Migrate from v3 to v4](https://ionicframework.com/docs/updating/4-0)
|
|
|
|
### Examples
|
|
|
|
The Ionic Conference App is a full featured Ionic app. It is the perfect starting point for learning and building your own app.
|
|
|
|
- [Angular Ionic Conference App](https://github.com/ionic-team/ionic-conference-app)
|
|
- [React Ionic Conference App](https://github.com/ionic-team/ionic-react-conference-app)
|
|
<!-- TODO(FW-3811): add this when the vue conference app is updated -->
|
|
<!-- - [Vue Ionic Conference App](https://github.com/ionic-team/ionic-vue-conference-app) -->
|
|
|
|
### Contributing
|
|
|
|
Thanks for your interest in contributing! Read up on our guidelines for
|
|
[contributing](https://github.com/ionic-team/ionic/blob/main/docs/CONTRIBUTING.md)
|
|
and then look through our issues with a [help wanted](https://github.com/ionic-team/ionic/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)
|
|
label.
|
|
|
|
Please note that this project is released with a [Contributor Code of Conduct](https://github.com/ionic-team/ionic/blob/main/CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
|
|
|
|
### Future Goals
|
|
|
|
As Ionic Framework components migrate to the web component standard, a goal of ours is to have Ionic Framework easily work within all of the popular frameworks.
|
|
|
|
### Earlier Versions
|
|
|
|
The source code for earlier versions of the Ionic Framework may exist in other repositories. Please open issues and pull requests in their respective repositories.
|
|
|
|
* **Ionic 2/3**: Moved to [`ionic-team/ionic-v3`](https://github.com/ionic-team/ionic-v3)
|
|
* **Ionic 1**: Moved to [`ionic-team/ionic-v1`](https://github.com/ionic-team/ionic-v1)
|