@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 from Docusaurus 2.x to 3.x

Upgrade the package.json dependencies to their newest versions
Run npm i --legacy-peer-deps, as @cmfcmf/docusaurus-search-local still depends on @docusaurus/core": "^2.0.0
Fix any mdx parsing errors (more here)