You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -44,50 +41,25 @@ The Ionic docs were originally built in a Mac-based environment, so Mac-focused
44
41
45
42
## Project Structure
46
43
47
-
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.
48
-
49
-
At a high level, the production documentation works like this:
50
-
51
-
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
52
-
```
53
-
pages/
54
-
├── index.json
55
-
└── index.md
56
-
```
57
-
2. At runtime, the `docs-page` component receives the current path (e.g. `/docs`)
58
-
3. The `docs-page` component fetches and parses the [JSON representation](https://ionicframework.com/docs/pages/index.json) of that page
59
-
4. The `docs-page` component renders that data using a [template](https://github.com/ionic-team/ionic-docs/tree/master/src/components/page/templates)
60
-
61
-
> **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.
44
+
Ionic's documentation is built using [Docusaurus](https://docusaurus.io/). The content is either written or generated as Markdown.
62
45
63
46
### Directories
64
47
65
-
-`scripts/` - build scripts used to generate JSON representations of each page and other data used in the docs
48
+
-`scripts/` - build scripts used to generate markdown or json files
66
49
-`src/` - source code and content of the docs
67
-
-`assets/` - static assets used on the site, like images and fonts
68
-
-`components/` - Stencil components used in the documentation UI
69
-
-`demos/` - Self-contained demos, optionally presented by pages via `demoUrl` YAML frontmatter
70
-
-`pages/` - Markdown content organized by route and uncommitted JSON representation of each page
71
-
-`styles/` - Global and page-specific styles (non-component styles)
72
-
73
-
### Page Templates
74
-
75
-
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.
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).
85
-
86
-
---
50
+
-`components/` - components used across the site
51
+
-`global/` - components used globally
52
+
-`page/` - components used on a single page or in a limited scope
53
+
-`styles/` - global styles and variables
54
+
-`components/` - styles split out into the components they target
55
+
-`static/`
56
+
-`demos/` - self-contained demos, optionally presented by pages via `demoUrl` YAML frontmatter
57
+
-`versioned_docs/` - versions of the docs created by the docusaurus versioning command
58
+
-`versioned_sitebars/` - versions of the docs sidebars created by the docusaurus versioning command
87
59
88
60
## Authoring Content
89
61
90
-
The content of the Ionic docs is written as [Markdown](https://commonmark.org/) in `src/pages`. Each Markdown file corresponds to a route.
62
+
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.
91
63
92
64
```
93
65
/docs/ => src/pages/index.md
@@ -98,50 +70,14 @@ The content of the Ionic docs is written as [Markdown](https://commonmark.org/)
98
70
99
71
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.
100
72
101
-
### Authoring Locally
102
-
103
-
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:
104
-
105
-
```sh
106
-
$ npm run watch-pages
107
-
```
108
-
109
-
> **Note**: the `watch-pages` script won't reload the page. You will need to reload the page manually after your page is rebuilt.
110
-
111
73
### Reference Content
112
74
113
-
The Markdown in `src/pages` does not contain all of the Ionic documentation's content:
75
+
The Markdown in `docs/` does not only contain manually written markdown files:
114
76
115
77
- Paths matching `/docs/api/*` are built from the [Ionic Framework](https://github.com/ionic-team/ionic) source code
116
78
- Paths matching `/docs/native/*` are built from the [Ionic Native](https://github.com/ionic-team/ionic-native) source code
117
79
- Paths matching `/docs/cli/commands/*` are built from the [Ionic CLI](https://github.com/ionic-team/ionic-cli) source code
118
80
119
-
#### Updating Ionic Native Community Plugins
120
-
121
-
To add or update an Ionic Native [community plugin](/docs/native/community):
122
-
1) Open a pull request on the [Ionic Native](https://github.com/ionic-team/ionic-native) repository (both code or documentation).
123
-
2) Once the change has been approved and merged into master by the Ionic team, do the following steps:
3) Open a PR in the `ionic-docs` repo, submitting the new `native.json` file.
142
-
143
-
---
144
-
145
81
## Translation
146
82
147
83
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.
@@ -152,26 +88,6 @@ _Please submit translation issues to the Crowdin page and not the Ionic Docs Git
152
88
153
89
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).
154
90
155
-
### Add new pages / Updating sidebar menus
156
-
157
-
When adding new pages to the docs, add a new token representing the page name to the appropriate Menu template (`src/components/menu/templates`).
158
-
159
-
For example, in `src/components/menu/templates/main.tsx`:
160
-
161
-
```javascript
162
-
// 'token': 'path'
163
-
'menu-intro-cli':'/docs/intro/cli',
164
-
```
165
-
166
-
Then, add the token and its translation to each file within the `src/assets/locales` folder:
167
-
168
-
For example, in `src/assets/locales/en/messages.json`:
169
-
170
-
```javascript
171
-
// 'token': 'translated text'
172
-
"menu-intro-cli":"CLI Installation",
173
-
```
174
-
175
91
## Reporting Issues
176
92
177
93
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
191
107
192
108
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.
193
109
194
-
> **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).
195
-
196
110
---
197
111
198
-
## Project Management
112
+
<!--## Project Management
199
113
200
114
Internally, the Ionic documentation team uses a [project board](https://github.com/ionic-team/ionic-docs/projects/3) to plan work on the docs. The lanes on the board are:
201
115
@@ -207,11 +121,11 @@ Internally, the Ionic documentation team uses a [project board](https://github.c
207
121
208
122
If you're looking for issues to help out with, we'd recommend either asking about an issue in the backlog or checking for issues labeled [`help-wanted`](https://github.com/ionic-team/ionic-docs/labels/help%20wanted).
209
123
210
-
---
124
+
----->
211
125
212
126
## Deploying
213
127
214
-
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.
128
+
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.
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.
4
+
5
+
## Versioning
6
+
7
+
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.
8
+
9
+
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/`.
10
+
11
+
## Auto Generated Files
12
+
13
+
All markdown files in these directories are generated from [scripts](/scripts):
0 commit comments