@ouc/docusaurus-plugin NPM

One Unity Documentation Plattform

Installation

Quick Setup

Simply run

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:

// @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:

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 .

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):

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

or multiple

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 :

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

or multiple

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:

    "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.

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.

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:

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

Update the @ouc/docusaurus-plugin package version in your package.json to the newest version

Add the following overrides property next to your dependencies in your package.json file:

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

Remove the node_modules folder (rm -r **/node_modules) and the package-lock.json (rm package-lock.json) file
Run npm i
Update the .gitingore file to exclude the docs/changelog folder
Remove files src/pages/index.jsx and src/pages/index.module.css
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.