Portal

The Portal manages a public documentation and blog site from inside the workspace. You write docs and blog posts as drafts in Crewhall, review the changes, and publish them. A separate Next.js site reads the published content and serves it to visitors with search, RSS feeds and a sitemap.

Who can use the Portal​

Portal sites belong to the organization, not to a space. Org admins create sites and change site settings. Admins can also give members permission to edit portal content, to publish it, or both. Guests never edit or publish the portal. If you have neither permission, Portal does not appear in your left menu.

Sites​

An organization can have more than one site. Use the site picker at the top of the Portal sidebar to switch sites, select New site, or open the Docusaurus import.

To create a site, fill in the site name, a Short name (used in app addresses such as /portal/docs-site), the languages separated by commas, and the First version. Then select Create site.

The sidebar of a site has these screens: Overview, Docs, Versions, Blog, Home page, Menu and footer, Media, SEO, Publish history, Import and Settings. Open site opens the public site.

Settings​

Settings is for site managers. It has four parts:

• Site: site name, domain, site title, tagline and public address.
• Languages: add a language (for example de), remove one, or select Make default. Set the Time zone (scheduled posts) here too.
• Next.js connection: the Content API address the site reads from, the Read key, the Revalidate endpoint (called on publish) and Preview mode (drafts and next). Use Test to check the connection. The read key is shown only once; store it in the Vault or in the site's environment variable. Rotate key stops the old key at once.
• Images: logo, dark theme logo, favicon and default social image.

Running the Next.js site itself is part of the server setup. See Self-hosting.

Overview​

Overview shows the site status: live URLs, unpublished changes, drafts and the translation status of each language. It also lists the unpublished changes with Review all, the publishing health (revalidate webhook, sitemap, search index), drafts, missing or outdated translations and recent publishes.

Docs​

Docs shows the Doc tree on the left. Pick a Version and a Language above the tree. Select New to add a New doc or a New category. A new doc is created as a draft in the source language of the selected version.

Each row in the tree has a menu with Move up, Move down and Move to category. A doc missing a translation is marked, for example "no tr".

A doc has these fields above the text:

A category has a Label, a Description and a Category page: Generated index lists the docs in it, No page makes it a plain group. A category must be empty before you delete it.

Deleting a published doc marks it To be removed. It disappears from the site on the next publish, and you can restore it until then.

Writing docs​

The doc editor is a block editor. Type / to insert blocks: headings, lists, to-do lists, quotes, code blocks with syntax highlighting, tables, tabs, toggles, bookmarks, videos, formulas, Mermaid diagrams, images, dividers and raw HTML.

Callout boxes (admonitions) are in the / menu as Note, Tip, Info, Warning and Danger. Change a box's type with Box type; Caution, Important, Success and Secondary are also available. Give the box an optional title.

The content is stored as Markdown. When you paste Markdown, including :::tip style admonitions, the editor converts it to blocks. Copy markdown in the doc's More actions menu copies the doc as Markdown. Images you add are uploaded to the site's media library.

Changes save automatically. If someone else saves the same doc while you edit, Crewhall tells you; copy your changes, then select Reload.

Select Preview in the top bar to open the doc on the site in preview mode with draft content. The preview link is valid for 1 hour.

Translations​

The source language is the site's default language. When a doc has no translation in the selected language, the site shows the source text at that language's address. To translate, open the doc in that language and select Start translation (copies the source text) or Start empty. The translation is a draft until you publish it.

Translation view, in the doc's More actions menu, shows the source text, read only, beside the translation. The copy button named after the source language (for example Copy English) replaces the translation with the source text.

When the source changes after a translation was last updated, the translation is marked Outdated. The site then shows a note that the translation may be behind. After you update it, select Mark as up to date.

Versions​

Docs are versioned. Versions lists them:

To release, select Freeze a new version. Enter the Version number and an optional Label for the version picker, and choose Freeze translations too if needed. Freezing copies next as it is now and cannot be undone. The copies appear on the site with the next publish.

Other actions on this screen:

• Make current version: /docs moves to that version, and the previous current version is archived.
• Show in the version picker: hides or shows a version in the site's picker.
• next is public: publishes /docs/next with an "Unreleased" banner.
• Old version banner: pages of archived versions link to the current release.

When you fix a doc in the current version, Apply to next too copies the change to next.

Blog​

Blog lists posts with their status, author, language, date and reading time. Filter by Published, Scheduled or Draft. Select New post to start one.

A post has a title, a cover image and the text. The reading time is calculated automatically. Under Post settings you set:

• Slug and Description (SEO and sharing).
• Authors: people in your organization, or an external author name.
• Tags: visitors can browse posts by tag.
• Publishing: Right away (when you press Publish) or Schedule with a date and time in the site's time zone.

Insert a Summary limit block to choose how much of the post shows in lists and RSS.

Media​

Media is the site's media library. Upload files, filter by Images, Documents or Unused, and set Alt text per language. Every file has a permanent /media address. Replace puts a new file at the same address, so links do not break. Used in shows where a file appears; a file in use cannot be deleted.

Menu and footer​

Menu and footer edits the site's navbar and footer. Labels are per language; addresses are shared.

• Navbar: add items to the left or right. Item kinds are Docs sidebar, Blog, Link, Doc, Language picker and Version picker. Hide or show any item.
• Title and logo: the site title and logo in the navbar.
• Footer: columns of links, a copyright line ({year} becomes the current year) and a dark or light footer color.

Use + Doc for internal links. If the doc's slug changes later, the menu follows it.

Home page​

Home page edits the site's landing page per language. Layout and animation stay in the site's code; here you edit text, images and lists. Select Add section and pick a type: Hero, About us, Video, Features card, Technologies, Community, Open source projects or Free text. Hide, show, reorder or remove sections. Empty fields show the source-language text.

SEO​

SEO has four tabs:

• Page settings: title, description (70 to 160 characters recommended), canonical address, social image, Let search engines index this page and Include in the sitemap. Previews show the Google result and the social card. Language versions are linked with hreflang automatically.
• Site defaults: the Title template with {page} and {site}, and the Default social image.
• Sitemap and robots: robots.txt and sitemap.xml are rebuilt on every publish.
• Redirects: add a redirect from an old address to a new one. When a published doc moves to a new address, publishing adds a redirect marked Automatic.

Import from Docusaurus​

An existing Docusaurus site can be imported. The import is started from the command line on the server by an administrator, with pnpm portal:import --from <docusaurus-repo>. Import then shows the report: imported docs, posts and categories, media, warnings, skipped files and how many URLs match the old site. If addresses are missing, add redirects under SEO › Redirects.

Publish​

Nothing reaches the public site until you publish. Each doc, post or setting shows a status: Draft, Published, Changed, To be removed or Scheduled. The top bar shows how many unpublished changes there are.

1. Select Publish in the top bar.
2. Review Changes to publish. Each change shows its kind and whether it is new, changed or being removed. Clear the ones you want to hold back.
3. Check URLs to refresh and add a Publish note if you like.
4. Select Publish.

Pages are rebuilt in the background and are usually live within seconds. Only the affected URLs are refreshed. Scheduled posts go live at their time.

Publish history​

Publish history lists every publish with its content, who published it and when, the URL count and the result: done, Running, Failed or Partly refreshed. Open a publish to see its changes and URLs.

• Revert on a single change, or Revert this whole publish, publishes the previous versions as a new publish. Nothing is deleted from the history.
• Retry refreshes a failed URL again. Failed URLs are retried three times, and the site keeps serving the old page until then.
• Cancel stops a scheduled item.

If a publish fails, you get a Portal notification.

Send a page from Pages​

You can turn a page from Pages into a portal doc. Open the page's menu and select Send to Portal. Choose the Site, Version and Language, then select Send as draft. Sending the same page again to the same version and language updates that draft.

Images on the page are copied to the portal media. Internal links become plain text, and mentions and embedded items are left out. Publish the draft from the Portal as usual.

The public site​

The public site shows only published content.

• Addresses: docs are at /docs/<version>/... for the default language and /<language>/docs/<version>/... for others. /docs opens the current version.
• Docs: a sidebar, breadcrumbs, an "On this page" list, previous and next links, copy buttons on code blocks, and a version picker and language picker in the navbar. Visitors can switch between light and dark mode.
• Search: a search box in the navbar and a full search page.
• Blog: post lists, tag pages, author pages and an archive.
• Feeds: RSS at /blog/rss.xml and Atom at /blog/atom.xml, rebuilt on every publish.
• Sitemap and robots: /sitemap.xml and /robots.txt.

Visitors see notes when a page is not translated yet, when a translation may be behind, or when they read an archived or unreleased version.