|
1 | | -# Website |
| 1 | +# Documentation website |
2 | 2 |
|
3 | | -This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. |
| 3 | +The documentation site for [`@ismailza/ngx-api-client`](https://www.npmjs.com/package/@ismailza/ngx-api-client), |
| 4 | +built with [Docusaurus](https://docusaurus.io/). |
4 | 5 |
|
5 | | -## Installation |
| 6 | +Published at **https://ismailza.github.io/ngx-api-client/**. |
| 7 | + |
| 8 | +## Local development |
| 9 | + |
| 10 | +From the repository root: |
6 | 11 |
|
7 | 12 | ```bash |
8 | | -npm install |
| 13 | +npm run docs:start |
9 | 14 | ``` |
10 | 15 |
|
11 | | -**Note**: feel free to use the package manager of your choice. |
12 | | - |
13 | | -## Local Development |
| 16 | +…or from this directory: |
14 | 17 |
|
15 | 18 | ```bash |
| 19 | +npm install |
16 | 20 | npm run start |
17 | 21 | ``` |
18 | 22 |
|
19 | | -This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. |
| 23 | +Most changes are reflected live without restarting the server. |
20 | 24 |
|
21 | 25 | ## Build |
22 | 26 |
|
23 | 27 | ```bash |
24 | | -npm run build |
| 28 | +npm run build # static output in ./build |
| 29 | +npm run serve # serve the production build locally |
| 30 | +npm run typecheck # type-check the site source |
25 | 31 | ``` |
26 | 32 |
|
27 | | -This command generates static content into the `build` directory and can be served using any static contents hosting service. |
28 | | - |
29 | | -## Deployment |
| 33 | +`npm run build` fails on broken internal links, so it is the check to run before |
| 34 | +opening a documentation pull request. |
30 | 35 |
|
31 | | -Using SSH: |
| 36 | +## Structure |
32 | 37 |
|
33 | | -```bash |
34 | | -USE_SSH=true npm run deploy |
| 38 | +``` |
| 39 | +docs/ |
| 40 | + intro.md What the library is and what it deliberately isn't |
| 41 | + getting-started/ Installation and quick start |
| 42 | + guides/ One page per concern (configuration, versioning, retry, …) |
| 43 | + api/ Reference for the public API surface |
| 44 | +src/ |
| 45 | + pages/index.tsx Landing page |
| 46 | + components/ Landing page sections |
| 47 | + css/custom.css Theme tokens |
| 48 | +sidebars.ts Explicit sidebar — new pages must be added here |
| 49 | +docusaurus.config.ts Site config, navbar, footer, deployment URL |
35 | 50 | ``` |
36 | 51 |
|
37 | | -Not using SSH: |
| 52 | +The sidebar is defined explicitly rather than autogenerated, so **a new page is |
| 53 | +invisible until it is listed in `sidebars.ts`**. |
38 | 54 |
|
39 | | -```bash |
40 | | -GIT_USER=<Your GitHub username> npm run deploy |
41 | | -``` |
| 55 | +## Writing conventions |
| 56 | + |
| 57 | +- Document what the code does, not what it might do — check the source in |
| 58 | + `projects/ngx-api-client/src/lib` before stating a default. |
| 59 | +- Every option table gives the type, the default, and whether it can be |
| 60 | + overridden per request. |
| 61 | +- Code samples are complete enough to paste into an application. |
| 62 | + |
| 63 | +## Deployment |
42 | 64 |
|
43 | | -If you are using GitHub Pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. |
| 65 | +`.github/workflows/docs.yml` builds the site on every pull request that touches |
| 66 | +`website/`, and deploys to GitHub Pages on push to `main`. No manual `npm run |
| 67 | +deploy` is needed. |
0 commit comments