npm package: @ouc/docusaurus-plugin
Description: One Unity main docusaurus plugin
Latest version: 2.0.2

# One Unity Documentation Plattform

## Installation

### Quick Setup

Simply run

```BASH
npx @ouc/docusaurus-plugin projectName projectType
```

*   `projectName`: The project name will appear later in url <https://developers.one-unity.cloud/ousp-template>
*   `projectType`: Choose between `"ousp"`, `"sdk"`, `"ecs"`

### Manual Installation

Add the package to your package.json and run

```
npm i
```

All required files will be copied from the one unity docusaurus plugin.

## Configuration

Now it's time to configure the docs.

### `docusaurus.config.js`

After installation you'll see a `docusaurus.config.js` in your project directory, that will look like:

```JS
// @ts-check
const {
    config
} = require("@ouc/docusaurus-plugin");

module.exports = config({
    projectName: "ousp-template",
    title: "One Unity Template",
    type: "ousp",
    version: require("./package.json").version,

    // Link to product, appears on landing page
    // productUrl: "https://one-unity.de/dms",

    // Provide a changelog
    // changelog: {
    //     changelogPath: "./CHANGELOG.md",
    // },

    // Provide generated types
    // api: {
    //     external: {
    //         label: "API-Reference",
    //         href: "https://some-service.one-unity.cloud/swagger/"
    //     },
    //     typings: {
    //         id: "portalscripts",
    //         title: "Portalscript API",
    //         dtsFiles: ["./library.d.ts"],
    //     },
    // },

    // Provide custom sidebars
    // sidebar: {
    //     Docs: ["introduction2"],
    // },
});
```

Now, first update your project informations.

*   `projectName`: The project name will appear later in url <https://developers.one-unity.cloud/ousp-template>
*   `title`: Project title (appears on landing page)
*   `type`: Choose between `"ousp"`,                `"sdk"`,                `"ecs"`,  `"sap"` or `"custom"`. Note: this will change the layout and icons
*   `version`: The displayed version

For further options see below or in vscode intellisense.

### Next steps

Replace all `ousp-template` with your choosen project name ( `projectName` from `docusaurus.config.js` ).

*   package.json (`ousp-template`)
*   nginx.conf (`ousp-template`)
*   dockerfile (`ousp-template`)

## Start

To start the website, simply use:

```BASH
npm run dev
```

## Advanced Setup

### Using a changelog

If you want to use a automated changelog, you can activate this in the `docusaurus.config.js` file, by using the `changelog` property.

Simply provide the path to the `CHANGELOG.md` .

```JS
changelog: {
    changelogPath: "../../CHANGELOG.md",
},
```

### Provide API informations

To provide API informations, you'll need a `api` property in your `docusaurus.config.js` .

#### External references

You can ether provide an external reference (for example Swagger UI):

```JS
api: {
    external: {
        label: "API-Reference",
        href: "https://some-service.one-unity.cloud/swagger/"
    },
}
```

or multiple

```JS
api: {
    external: [{
            label: "API-Reference",
            href: "https://some-service.one-unity.cloud/swagger/"
        },
        {
            label: "API-Reference Legacy",
            href: "https://some-service.one-unity.cloud/swagger-legacy/"
        }
    ],
}
```

#### Generate by using `.d.ts` files

To provide a automated docs from `d.ts` files, you can use the property `typings` :

```JS
api: {
    typings: {
        id: "portalscripts",
        title: "Portalscript API",
        dtsFiles: ["../ousp-project/dist/compiled/typings/ousp-project.d.ts"],
    },
},
```

or multiple

```JS
api: {
    typings: [{
            id: "portalscripts",
            title: "Portalscript API",
            dtsFiles: ["../ousp-project/dist/compiled/typings/ousp-project.d.ts"],
        },
        {
            id: "client",
            title: "Clientscripts API",
            dtsFiles: ["../ousp-project/dist/compiled/typings/ousp-project.client.d.ts"],
        },
    ],
}
```

Next update the tsconfig.typedoc.json and add a include array:

```js
    "include": [
        "../ousp-project/dist/compiled/typings/ousp-project.d.ts"
    ]
```

### Other configurations

#### Custom logo

Use can use a custom logo, by using the `logo` prop.

```JS
logo: "img/my-logo.png"
```

The image must be stored in following directory: `rootDir/src/static` .

#### Product links

Use the `productUrl` prop for display a Button on the landing page.

```JS
productUrl: "https://one-unity.de/dms"
```

## Writing docs

In the `rootDir/docs` you'll see predefined structure. FIRST: Do not delete the files!

```
api/
    introduction
documentation/
    introduction
    first-steps/
        first-steps
        glossary

```

Place all new files below `/docs/documentation` .

Like `/docs/documentation/my-fancy-doc.md` :

```
---
sidebar_position: 1
id: my-fancy-doc
title: My fancy doc
---

# Hello!

My content here
```

### Sidebars

Sidebars are autogenerated. To reorder or modify categories, you can use metadata.

To reorder your docs, follow <https://docusaurus.io/docs/sidebar/autogenerated#doc-item-metadata> or look at the `docs/documentation/introduction.md`

New folder will appear as category. To modify the category, follow <https://docusaurus.io/docs/sidebar/autogenerated#category-item-metadata> or look at the `docs/documentation/first-steps/_category_.json`

#### Hardcoded sidebar entries

Additional you can add a sidebar in the `docusaurus.config.js` by using:

```JS
sidebar: {
    Docs: ["my-fancy-doc"],
},
```

## Integrate with atlas

*   You need a private docker repo like `https://hub.docker.com/repository/docker/oneunity/ousp-library-docs`
*   The Repo must have a postfix `-docs`
*   The Docker image must be built from dockerfile (nginx with subfolder)
*   Integrate your project, by following instruction on <https://bitbucket.org/one-unity/atlas/>

## Upgrade Plugin from 1.x to 2.x

1. Update the `@ouc/docusaurus-plugin` package version in your `package.json` to the newest version
2. Add the following `overrides` property next to your `dependencies` in your `package.json` file:

    ```json
    "dependencies": {
        ...
    },
    "overrides": {
        "@cmfcmf/docusaurus-search-local": {
            "@docusaurus/core": "3.3.2"
        }
    },
    ```

3. Remove the `node_modules` folder (`rm -r **/node_modules`) and the `package-lock.json` (`rm package-lock.json`) file
4. Run `npm i`
5. Update the `.gitingore` file to exclude the `docs/changelog` folder
6. Remove files `src/pages/index.jsx` and `src/pages/index.module.css`
7. If enabled, check the broken links to the API documentation in the markdown files

### Breaking Changes

In this version, the layout of the documentation portal has been changed. The following changes have been made:

#### Navbar

The navbar now contains only the "Dokumentation" (docs) entry. The remaining entries ('API', 'Changelog') are now located in the Sidebar (see below). The title is now by default `One Unity Developer Dokumentationsportal` and is not changeable.

#### Sidebar

The sidebar now contains all available solutions/products as links. A complete list of all available solutions/products can be found in the `solutions.json`.

If the current project matches one of the solutions/products, the sidebar entry will be replaced with:

*   All Entries from `documentation` (`autogenerated` from `docs/documentation`)
*   `API` (`autogenerated` from `docs/api`)
*   `Changelog` (`autogenerated` from `docs/changelog`)

✅ Now, that all solutions/products are listed in the sidebar, consider to collapse expanded categories in the sidebar.

#### Changelog

Previously, the changelog was generated with multiple blog posts. Now the changelog are multiple markdown files in the `docs/changelog` folder and were sorted displayed in sidebar "Changelog". These files are generated automatically and should not be edited manually. For this reason, you should exclude the `docs/changelog` folder from git in your `.gitignore` file.

#### Landing Page

Due to the new sidebar, the landing page has been removed. The landing page links now to `/`.
Following steps are needed:

*   Change slug in `/docs/documentation/introduction.md` from `slug: /documentation` to `slug: /`.
*   Remove the `src/pages/index.jsx` and `src/pages/index.module.css` files.

#### Type definitions

The typedoc plugin has also been updated to a newer version. With this upgrade, the `/docs/api` folder gets a new structure. The `api` entry from the navbar is now replaced by the `API` entry from the sidebar.

*   Please check the broken links in the markdown files!