mirror of
https://github.com/codex-team/codex.docs.git
synced 2025-07-19 05:09:41 +02:00
chore(readme): readme update (#263)
* chore(readme): readme update * write about configuration
This commit is contained in:
Peter Savchenko
GitHub
parent
47198af8bc
commit
2a8684296b
1 changed files with 47 additions and 92 deletions
139
README.md
139
README.md
|
|
@ -1,115 +1,70 @@
|
|||
# CodeX Docs
|
||||
|
||||
CodeX Docs is a simple but powerful documentation engine for CodeX powered with [Editor.js](//editorjs.io).
|
||||
[CodeX Docs](https://docs.codex.so/) is a free docs application. It's based on Editor.js ecosystem which gives all modern opportunities for working with content.
|
||||
|
||||
You can use CodeX Docs for product documentation, for internal team docs, or for any other documentation.
|
||||
You can use it for product documentation, for internal team docs, for personal notes or any other need.
|
||||
|
||||
|
||||
|
||||
|
||||
## Development
|
||||
It's super easy to install and use.
|
||||
|
||||
### Prerequisites
|
||||
## Features
|
||||
|
||||
- NodeJS (v16.x)
|
||||
- npx (installed by default with npm)
|
||||
- Yarn
|
||||
- 🤩 [Editor.js](https://editor.js/?from=docs-demo) ecosystem powered
|
||||
- 📂 Docs nesting — create any structure you need
|
||||
- 📱 Nice look on Desktop and Mobile
|
||||
- 🔥 Beautiful page URLs. Human-readable and SEO-friendly.
|
||||
- 🦅 [Hawk](https://hawk.so/?from=docs-demo) is hunting. Errors tracking integrated
|
||||
- 💌 [Misprints](https://github.com/codex-team/codex.misprints) reports to the Telegram / Slack
|
||||
- 📈 [Yandex Metrica](https://metrica.yandex.com/about) integrated
|
||||
- 🚢 Deploy easily — no DB and other deps required
|
||||
- 🤙 Simple configuration
|
||||
- ⚙️ Tune UI as you need. Collapse sections, hide the Sidebar
|
||||
|
||||
### Install npm packages
|
||||
## Demo
|
||||
|
||||
Here is our [Demo Application](https://docs-demo.codex.so/) where you can try CodeX Docs in action.
|
||||
|
||||
## Guides
|
||||
|
||||
1. [Getting Started](https://docs.codex.so/getting-started)
|
||||
2. [Configuration](https://docs.codex.so/configuration)
|
||||
3. [Deployment](https://docs.codex.so/deployment)
|
||||
4. [Authentication](https://docs.codex.so/authentication)
|
||||
5. [Writing](https://docs.codex.so/writing)
|
||||
6. [How to enable analytics](https://docs.codex.so/yandex-metrica)
|
||||
7. [Contribution guide](https://docs.codex.so/contribution)
|
||||
|
||||
## Getting Started
|
||||
|
||||
### 1. Clone the repo.
|
||||
|
||||
```shell
|
||||
yarn install --frozen-lockfile
|
||||
yarn add @codexteam/docs
|
||||
```
|
||||
|
||||
### Create config file
|
||||
### 2. Fill the config
|
||||
|
||||
Read about available [configuration](https://docs.codex.so/configuration) options.
|
||||
|
||||
### 3. Run the application
|
||||
|
||||
#### Using Yarn
|
||||
|
||||
```shell
|
||||
cp .codexdocsrc.sample .codexdocsrc
|
||||
cp .env.sample .env
|
||||
yarn && yarn start
|
||||
```
|
||||
|
||||
### Run application (both frontend and backend)
|
||||
#### Using Docker
|
||||
|
||||
```shell
|
||||
yarn dev
|
||||
```
|
||||
docker-compose build
|
||||
docker-compose up
|
||||
```
|
||||
|
||||
Then you can open browser and navigate to [http://localhost:3000](http://localhost:3000).
|
||||
#### Using Kubernetes
|
||||
|
||||
Now you can [authenticate](https://github.com/codex-team/codex.docs/#authentication) in the application and start creating your documentation.
|
||||
|
||||
### Available scripts
|
||||
|
||||
#### Start whole application (backend and frontend in watch mode)
|
||||
|
||||
```shell
|
||||
yarn dev
|
||||
```
|
||||
|
||||
#### Start backend in development mode
|
||||
|
||||
```shell
|
||||
yarn start-backend
|
||||
```
|
||||
|
||||
#### Compile TypeScript files
|
||||
|
||||
```shell
|
||||
yarn compile
|
||||
```
|
||||
|
||||
#### Build frontend
|
||||
|
||||
To build frontend sources run the following command:
|
||||
|
||||
```shell
|
||||
yarn build-frontend
|
||||
```
|
||||
|
||||
To build frontend and watch for changes run the following command:
|
||||
|
||||
```shell
|
||||
yarn build-frontend:dev
|
||||
```
|
||||
|
||||
#### Run ESLint with `--fix` option
|
||||
|
||||
```shell
|
||||
yarn lint
|
||||
```
|
||||
|
||||
#### Run tests
|
||||
|
||||
```shell
|
||||
yarn test
|
||||
```
|
||||
|
||||
### Setup
|
||||
|
||||
You can configure application using configs in <code>/config</code> directory.
|
||||
|
||||
| Property | Role |
|
||||
|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| <code>port</code> | to set port of application |
|
||||
| <code>database</code> | to name directory with data |
|
||||
| <code>rcFile</code> | to set destination of codexdocsrc config file |
|
||||
| <code>uploads</code> | to set destination of directory to save uploads |
|
||||
| <code>secret</code> | to set secret |
|
||||
| <code>favicon</code> | to set url or favicon path (favicon need to be in /public directory), like `/myFavicon.png`, to get favicon. Server uploads file by url and saves it to temporary directory. And you can get favicon by /favicon static route of application |
|
||||
|
||||
You can configure application using configs in <code>/config</code> directory.
|
||||
|
||||
### Authentication
|
||||
|
||||
To manage pages you need to authorize (available on `/auth`).
|
||||
|
||||
To set password, set the `PASSWORD` environment variable inside the `.env` file.
|
||||
|
||||
## Release process
|
||||
|
||||
We use [release-drafter](https://github.com/release-drafter/release-drafter) to generate release notes and GitHub release.
|
||||
It will automatically generate draft release based pull requests data between current version and previous version.
|
||||
To make new release you need go to [releases](https://github.com/codex-team/codex.docs/releases) page find the latest draft release and mark it as ready.
|
||||
After creating new release, new git tag will be created and new version will be published.
|
||||
We have the ready-to-use [Helm chart](https://github.com/codex-team/codex.docs.chart) to deploy project in Kubernetes
|
||||
|
||||
# About CodeX
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue