Running the Handbook in Workspace

Instructions for running the Handbook projects in Workspace

You can use cloud-based workspaces to develop and preview the handbook without installing dependencies locally. This approach provides a consistent, pre-configured development environment.

GitLab Workspaces

GitLab Workspaces provides cloud-based development environments directly integrated with GitLab repositories.

Prerequisites

You must have at least the Developer role for the Handbook repositories.

Start a workspace

To start a workspace:

Go to one of the following repositories:
- The Handbook repository or a relevant merge request.
- The Internal Handbook repository or a relevant merge request.
Select Code > Open in Workspace or New Workspace.
From the Cluster agent dropdown list, select the available agent configuration.
From the Devfile dropdown list, select one of the following:
- .devfile.yaml if there is a custom devfile in your project. Custom devfiles are configured for your specific project needs.
- Use GitLab default devfile for a quick start without project-specific configuration.
For more information, see Devfile.
Select Create workspace.
Wait for the workspace to initialize and reach running status.

Run the handbook

The workspace runs initial setup commands (asdf install && npm install) automatically through a post-start script.

Monitor setup progress

To check the progress of the post-start command:

cat /projects/workspace-logs/poststart-stderr.log
cat /projects/workspace-logs/poststart-stdout.log

Note

Wait for the post-start command to complete before you continue with development tasks.

Start the development server

After initial setup completes, follow the standard steps for running Hugo server. The following are some common commands:

# Sync data files and start Hugo server
# Hugo command takes approximately 20-30 minutes to finish
./scripts/sync-data.sh
hugo --logLevel debug
hugo server --bind 0.0.0.0 # bind option should be used for hugo server in workspace

# Run Markdown linting
markdownlint-cli2 "content/**/*.md"

# Run Markdown linting with Docker
sudo dockerd
sudo docker run --rm -v $(pwd):$(pwd) -w $(pwd) davidanson/markdownlint-cli2 content/**/*.md

Commit changes

To commit your changes:

# Stage your changes
git add .

# Commit with a descriptive message
git commit -m "docs: update workspace documentation"

# Push to your feature branch
git push origin feature-branch-name

Troubleshooting

Port forwarding issues

If you cannot access the Hugo server:

Verify that port 1313 is configured for forwarding in devfile.yaml.
Ensure Hugo is bound to 0.0.0.0 rather than localhost.
Access the Hugo server by using the workspace’s port-specific URL format.

Access the Hugo server

Replace the port number (60001) with 1313 in your workspace URL to access the Hugo development server.

Your workspace URL follows this pattern:

https://60001-workspace-1103912-20874665-nfnxvo.workspaces.gitlab.dev/

The Hugo server is accessible at:

https://1313-workspace-1103912-20874665-nfnxvo.workspaces.gitlab.dev/

Further workspace-specific issues

See the GitLab Workspaces documentation.
Reach out in the Slack #f_workspaces channel.
Create an issue in the Workspace User Feedback Epic.

View page source - Edit this page - please contribute.