Dev Portal Migration Guide
This documentation is for the preview version of the Dev Portal. If you aren't part of the preview program, please refer to the current Dev Portal docs.
This guide is intended to help you migrate your existing documentation from the current Dev Portal to the new Dev Portal powered by Zudoku.
Setup
The migration to the new Developer Portal powered by Zudoku is currently a manual process. You will need to clone your existing Zuplo project locally to perform these steps.
Project Structure
There are a few changes to the project structure that you should be aware of:
- The
dev-portal.json
file in theconfig
directory will go away and you will migrate to use the newzudoku.config.ts
file in thedocs
directory. - Markdown files are now located in the
docs/pages
directory. - There needs to be a
tsconfig.json
andpackage.json
file in thedocs
directory to build the documentation.
Below is an example of the new project structure. The steps below will explain what's needed for each file.
my-api/ ├─ config/ │ ├─ routes.oas.json │ ├─ policies.json ├─ docs/ │ ├─ zudoku.config.ts │ ├─ package.json │ ├─ tsconfig.json │ ├─ pages/ │ │ ├─ doc.md # <- Your existing markdown files ├─ .gitignore ├─ package.json ├─ tsconfig.json ├─ README.mdtxt
zudoku.config.ts
The dev-portal.json
file in the config
directory will be replaced with the
new zudoku.config.ts
file in the docs
directory. This file will contain the
configuration for the new Dev Portal powered by Zudoku. You can find more
information about the configuration in the
Dev Portal Configuration documentation.
Your existing dev-portal.json
file will look something like this. You will
also have a sidebar.json
file in the docs
directory.
{ "pageTitle": "My API", "faviconUrl": "https://www.example.org/favicon.ico", "enableAuthentication": true, "authentication": { "provider": "auth0", "authority": "$env(ZUPLO_PUBLIC_AUTH0_AUTHORITY_URL)", "jwksUrl": "$env(ZUPLO_PUBLIC_AUTH0_AUTHORITY_URL).well-known/jwks.json", "devPortalClient": { "clientId": "$env(ZUPLO_PUBLIC_AUTH0_CLIENT_ID)", "audience": "$env(ZUPLO_PUBLIC_AUTH0_AUDIENCE_URL)" } }, "generateExamples": true }json
Migrated to the new format of configuration, this file would look like the following.
Note that the environment variables are referenced by simply using
process.env
. See environment variables
import type { ZudokuConfig } from "zudoku"; import withZuplo from "zudoku/with-zuplo"; const config: ZudokuConfig = { basePath: "/docs", topNavigation: [ { id: "documentation", label: "Documentation" }, { id: "api", label: "API Reference" }, ], sidebar: { documentation: [ { type: "category", label: "Overview", items: ["introduction", "other-example"], }, ], }, redirects: [{ from: "/", to: "/introduction" }], apis: { type: "file", input: "../config/routes.oas.json", navigationId: "api", }, docs: { files: "/pages/**/*.{md,mdx}", }, authentication: { type: "auth0", domain: process.env.ZUPLO_PUBLIC_AUTH0_DOMAIN, clientId: process.env.ZUPLO_PUBLIC_AUTH0_CLIENT_ID, }, }; export default withZuplo(config);ts
Markdown Files
Markdown files should be moved to the docs/pages
directory. You can use
subdirectories under this as needed.
tsconfig.json
and package.json
You will need to create a tsconfig.json
and package.json
file in the docs
folder. You can copy these two files below.
tsconfig.json
{ "compilerOptions": { "target": "ES2022", "lib": ["ESNext", "DOM", "DOM.Iterable", "WebWorker"], "module": "ESNext", "moduleResolution": "Bundler", "useDefineForClassFields": true, "skipLibCheck": true, "skipDefaultLibCheck": true, "resolveJsonModule": true, "isolatedModules": true, "useUnknownInCatchVariables": false, "types": ["zudoku/client"], "jsx": "react-jsx" } }json
package.json
{ "name": "docs", "version": "0.1.0", "type": "module", "private": true, "scripts": { "dev": "zudoku dev", "build": "zudoku build" }, "dependencies": { "react": ">18.0.0", "react-dom": ">18.0.0", "zudoku": "^0.20" }, "devDependencies": { "typescript": "^5", "@types/node": "^20", "@types/react": "^18", "@types/react-dom": "^18" } }json
Theme
For instructions on theming the dev portal, see customizing.
Additional theming is possible. More documentation is coming soon.
Cleanup
Make sure to delete the following files after you are done with the migration:
/config/dev-portal.json
/docs/sidebar.json
/docs/theme.css