Star

MIT License
Copyright © 2020
CONNECT-platform

linkCLI

The CLI is the recommended way of using CODEDOC. To install it, you would need the following first:

After installing the above, you can easily install codedoc CLI via NPM:

1npm i -g @codedoc/cli


linkSetting Up a Project

1cd <my-project>

2codedoc init # --> you could also use `codedoc i`

The init command will create the .codedoc/ folder in your project and populate it with some initial setup, and also add some boiler-plate markdown files in docs/ folder for you to get started.

Codedoc will try to automatically guess a good title for your documentations, based on your project's repo and its folder name. To congiure your project according to your preferences, simply modify contents of .codedoc/config.ts:

.codedoc/config.ts
1import { configuration } from '@codedoc/core';

2

3import { theme } from './theme';

4

5

6export const config = /*#__PURE__*/configuration({

7 theme,

8 page: {

9 title: {

10 base: 'My Project' // --> the title of your docs

11 },

12 },

13});

If your project folder is version controlled by git with the remote set to a GitHub repository, it will automatically configure GitHub integrations for you as well.


linkCloning Existing Projects

When you clone an existing project that is already setup (i.e. has a .codedoc folder in its repo), you still need to install local dependencies (in .codedoc/node_modules) to be able to build/serve the files locally.

For this purpose, you can use codedoc install command:

1git clone <my-awsome-project>.git # --> so my-awseome-project is an already setup

2cd my-awesome-project # --> lets go inside

3codedoc install # --> and install local dependencies.


linkDevelopment

CODEDOC comes with a nice development server that constantly watches, rebuilds and serves your docs on your local machine:

1codedoc serve # --> Or alternatively, `codedoc s` or `codedoc w`.

The development server by default serves your docs on local port 3000, though you can change that in .codedoc/config.ts:

.codedoc/config.ts
1// ...

2

3export const config = /*#__PURE__*/configuration({

4 // ...

5 dev: {

6 port: 3002 // --> now the dev server serves on port 3002.

7 },

8 // ...

9});

Additionally, if your project is a GitHub repo, for example named my-repo, then by default the dev server will serve the docs on localhost:3000/my-repo/ (and not localhost:3000). This is to mimic the behaviour of GitHub Pages in case a custom domain is not used, and can be configured via .codedoc/config.ts as well:

.codedoc/config.ts
1// ...

2

3export const config = /*#__PURE__*/configuration({

4 // ...

5 dest: {

6 // ...

7 namespace: '/x' // --> now the dev server serves on `localhost:3000/x`.

8 },

9 // ...

10});


touch_app PROJECT NAMESPACE

Project namespace is basically for situations where your docs are not going be served at the root URL of your domain. For example, when you are publishing to GitHub Pages without using a custom domain, the URL your docs will be served on:

1https://<user-name>.github.io/<repo-name>

Then:

Learn More

linkUsing Docker

Projects initialized using codedoc init also include a Dockerfile and a docker-compose.yml file. If you want to run the development server inside a container, you can just run this:

1docker-compose up

warning WARNING

If you want to use your own custom docker setup, be careful not to volume .codedoc/node_modules folder. The host environment and the container environment typically differ greatly and should not share modules. It is always a good idea to start from the default docker configuration:


linkPublishing

If you want to publish your docs, you need to build them for production:

1codedoc build # --> Or simply `codedoc b`.


warning WARNING

Running codedoc serve would overwrite your built files, so make sure to always run codedoc build before publishing your docs.


linkUpdates

You can check whether the CLI or the local installation of codedoc require any updates via the version command:

1codedoc version # --> Or simply `codedoc v`.

In case you need to update the CLI or the local installation, simply use the update command:

1codedoc update # --> Or simply `codedoc u`.


linkMajor Updates

update command will not upgrade the CLI or local installation to the latest if there is a major update between your installed version and the latest version. This is because major updates might include breaking changes (by definition).

If you are sure that there are no breaking changes in the update that would affect you, you could update to latest version using update latest command:

1codedoc update latest # --> Forcefully update everything to latest version

update VERSION NOTICE

The update latest command is only available since @codedoc/cli@0.2.0, so if you have a version before that, you need to upgrade using npm i -g @codedoc/cli@latest.


linkUpdate Permissions

By default, update and update latest commands will attempt to update both the CLI and the local installation (if run in a CODEDOC project folder). In some shell environments, you might not have permissions to update the CLI, while you do have permissions to update the local installation. In such situations, you can use the --local flag to only update your local installation:

1codedoc update --local # --> Only update local installation, to latest compatible version

2codedoc update latest --local # --> Only update local installation, to latest version

update VERSION NOTICE

The --local flag is only available since @codedoc/cli@0.2.1, so if you have a version before that, you need to upgrade using codedoc update or npm i -g @codedoc/cli@latest.

CLISetting Up a ProjectCloning Existing ProjectsDevelopmentUsing DockerPublishingUpdatesMajor UpdatesUpdate Permissions

Home Overview CLI Theme

Markdownchevron_right
Code Featureschevron_right

Images & Assets

Configurationchevron_right
Customizationchevron_right