From 3e045148b15759b8c83f73a0781d16db4818645c Mon Sep 17 00:00:00 2001 From: hieu-jan <150573299+hieu-jan@users.noreply.github.com> Date: Sun, 10 Mar 2024 17:27:58 +0900 Subject: [PATCH] docs: update website-docs content --- docs/README.md | 60 +++++++------ docs/docs/.gitignore | 1 + .../how-we-work/website-docs/website-docs.md | 87 ++++++++++++++++++- 3 files changed, 119 insertions(+), 29 deletions(-) create mode 100644 docs/docs/.gitignore diff --git a/docs/README.md b/docs/README.md index b5d31702f..2b27b354b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,18 +1,18 @@ -# Website +This website is built using [Docusaurus 3.0](https://docusaurus.io/), a modern static website generator. -This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. - -## Information Architecture +### Information Architecture We try to **keep routes consistent** to maintain SEO. -- `/guides`: Guides on how to use the Jan application, with GIFs. For end users who are directly using Jan. Always assume users are not technical. +- **`/guides/`**: Guides on how to use the Jan application. For end users who are directly using Jan. -- `/developer`: Developer docs on how to extend Jan. These pages are about what people can build with our software. We must hide the complexity of HOW the app is built, but explain just enough of the high level architecture so devs know enough to build on top of it. +- **`/developer/`**: Developer docs on how to extend Jan. These pages are about what people can build with our software. -- `/api-reference`: Reference documentation, written in Swagger/OpenAPI format. +- **`/api-reference/`**: Reference documentation for the Jan API server, written in Swagger/OpenAPI format. -- `/docs`: Engineering specs and product specs, i.e. HOW the app is built. Mostly for internal reference and for our core contributors who are building the SDK itself. +- **`/changelog/`**: A list of changes made to the Jan application with each release. + +- **`/blog/`**: A blog for the Jan application. ### Sidebar Autogeneration @@ -20,34 +20,36 @@ The order of each page is either explicitly defined in `sidebar.js` or follows t Important slugs are hardcoded at the document level (and shouldn't be rerouted): -```md +``` --- title: Overview slug: /docs --- ``` -## Contributing +## How to Contribute -### Installation +Refer to the [Contributing Guide](https://github.com/janhq/jan/blob/dev/CONTRIBUTING.md) for more comprehensive information on how to contribute to the Jan project. -``` -$ yarn -``` +### Pre-requisites and Installation -### Local Development +- [Node.js](https://nodejs.org/en/) (version 20.0.0 or higher) +- [yarn](https://yarnpkg.com/) (version 1.22.0 or higher) -``` -$ cp .env.example .env -$ yarn start +#### Installation + +```bash +cd jan/docs +yarn install +yarn start ``` This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. -### Build +#### Build -``` -$ yarn build +```bash +yarn build ``` This command generates static content into the `build` directory and can be served using any static contents hosting service. @@ -56,25 +58,27 @@ This command generates static content into the `build` directory and can be serv Using SSH: -``` -$ USE_SSH=true yarn deploy +```bash +USE_SSH=true yarn deploy ``` Not using SSH: -``` -$ GIT_USER= yarn deploy +```bash +GIT_USER= yarn deploy ``` 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. ### Preview URL, Pre-release and Publishing Documentation -When a PR is created, the preview URL will be automatically commented on the PR. +- When a pull request is created, the preview URL will be automatically commented on the pull request. -The documentation will then be published to [https://jan.ai/](https://jan.ai/) when the PR is merged to `main`. +- The documentation will then be published to [https://dev.jan.ai/](https://dev.jan.ai/) when the pull request is merged to `dev`. + +- Our open-source maintainers will sync the updated content from `dev` to `docs` branch, which will then be published to [https://jan.ai/](https://jan.ai/). ### Additional Plugins - @docusaurus/theme-live-codeblock -- [Redocusaurus](https://redocusaurus.vercel.app/): manually upload swagger files at `/openapi/OpenAPISpec.json` +- [Redocusaurus](https://redocusaurus.vercel.app/): manually upload swagger files at `/openapi/jan.yaml` to update the API reference documentation. diff --git a/docs/docs/.gitignore b/docs/docs/.gitignore new file mode 100644 index 000000000..ff2a8c5fd --- /dev/null +++ b/docs/docs/.gitignore @@ -0,0 +1 @@ +guides/changelogs \ No newline at end of file diff --git a/docs/docs/how-we-work/website-docs/website-docs.md b/docs/docs/how-we-work/website-docs/website-docs.md index a152c6dc9..19fdc1676 100644 --- a/docs/docs/how-we-work/website-docs/website-docs.md +++ b/docs/docs/how-we-work/website-docs/website-docs.md @@ -1,3 +1,88 @@ --- title: Website & Docs ---- \ No newline at end of file +--- + +This website is built using [Docusaurus 3.0](https://docusaurus.io/), a modern static website generator. + +### Information Architecture + +We try to **keep routes consistent** to maintain SEO. + +- **`/guides/`**: Guides on how to use the Jan application. For end users who are directly using Jan. + +- **`/developer/`**: Developer docs on how to extend Jan. These pages are about what people can build with our software. + +- **`/api-reference/`**: Reference documentation for the Jan API server, written in Swagger/OpenAPI format. + +- **`/changelog/`**: A list of changes made to the Jan application with each release. + +- **`/blog/`**: A blog for the Jan application. + +### Sidebar Autogeneration + +The order of each page is either explicitly defined in `sidebar.js` or follows the [Docusaurus autogenerated](https://docusaurus.io/docs/next/sidebar/autogenerated) naming format, `##-path-name.md`. + +Important slugs are hardcoded at the document level (and shouldn't be rerouted): + +``` +--- +title: Overview +slug: /docs +--- +``` + +## How to Contribute + +Refer to the [Contributing Guide](https://github.com/janhq/jan/blob/dev/CONTRIBUTING.md) for more comprehensive information on how to contribute to the Jan project. + +### Pre-requisites and Installation + +- [Node.js](https://nodejs.org/en/) (version 20.0.0 or higher) +- [yarn](https://yarnpkg.com/) (version 1.22.0 or higher) + +#### Installation + +```bash +cd jan/docs +yarn install +yarn start +``` + +This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. + +#### Build + +```bash +yarn build +``` + +This command generates static content into the `build` directory and can be served using any static contents hosting service. + +### Deployment + +Using SSH: + +```bash +USE_SSH=true yarn deploy +``` + +Not using SSH: + +```bash +GIT_USER= yarn deploy +``` + +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. + +### Preview URL, Pre-release and Publishing Documentation + +- When a pull request is created, the preview URL will be automatically commented on the pull request. + +- The documentation will then be published to [https://dev.jan.ai/](https://dev.jan.ai/) when the pull request is merged to `dev`. + +- Our open-source maintainers will sync the updated content from `dev` to `docs` branch, which will then be published to [https://jan.ai/](https://jan.ai/). + +### Additional Plugins + +- @docusaurus/theme-live-codeblock +- [Redocusaurus](https://redocusaurus.vercel.app/): manually upload swagger files at `/openapi/jan.yaml` to update the API reference documentation.