The Beman Project Website

This is the repository hosting the code for the future Beman Website: https://bemanproject.org/.

This website is built using Docusaurus, a modern static website generator. Documentation is written in MDX format. Building and deploying it requires Node and NPM.

Add a blog post

1. Repository setup: create a local clone or open in Codespaces.

2. Create a directory having an index.md file using this pattern: blog/YYYY-MM-DD-tile-of-post/index.md:

Example:

$ tree blog/2000-10-30-my-blog-example/
blog/2000-10-30-my-blog-example/
├── images
│   └── beman_logo.png # images are stored in ./images/
└── index.md           # actual blog post content

2 directories, 2 files

3. Add your full Markdown blog post content inside the index.md file.

Example

$ cat blog/2000-10-30-my-blog-example/index.md
---
slug: my-blog-example-slug    # Slug example. Remove this comment if using this template.
authors: [neatudarius]        # Authors list with entrie from blog/authors.yml. Remove this comment if using this template.
tags: ["cpp26", "beman-docs"] # Blog post valid tags from blog/tags.yml. Remove this comment if using this template.
---

# My Blog Example

This is my blog example.

Here I can write Markdown content.
[...]

Add the author if not already present in blog/authors.yml

If this is your first time writing a blog post, you have to add yourself as an author in the blog/authors.yml file. Add a new entry using the following format:

<AuthorTag>:    # Your author tag, this is what you will use in the header section for a log.
name:           # Your Real Name.
title:          # Your title, how do you want to be recognized by other people.
url:            # Your Github profile page
image_url:      # A url for your profile image (for Github profile image: go to your profile, click on your image and open it in a new tab, copy the link).
page: true      # If an author page should be generated for you.
socials:        # [optional] Include your socials (like your Github, X, Linkedin etc)
    github: <yourId>      # [optional] Add GitHub page.
    linkedin: <yourId>    # [optional] Add LinkedIn page.
    x: <yourId>           # [optional] Add X page.

4. Open a DRAFT PR and wait up to one minute for a preview deployment of your blog post.

• Draft PR example: Add blog post: My Blog Example #54.

• Click on the Deploy Preview URL (format https://deploy-preview-${PR NUMBER}--bemanproject.netlify.app/).

• Successful CI preview deployment example:

• Test your deployment.

[DEBUG] Inspect CI preview deployment error logs.

The CI preview deployment logs should be public. Please ping a codeowner otherwise.

• DRAFT PR example with CI preview deployment error - #49.

• Click on the Latest deploy log URL - e.g., https://app.netlify.com/sites/bemanproject/deploys/6809108974fd910008633aa9.

• Logs inspect example:

• Fix the error, commit and push the changes. Wait for new deployment.

If you need to browse through more recent CI preview deployments logs use https://app.netlify.com/sites/bemanproject/deploys/. Note: netlify provides a single a single CI preview deployment for each PR - latest commit, but stores logs for multiple ones.

[DEBUG] Inspect local deployment error logs.

• On local setup, run make (see Local development) and check if there is any error in the console - example:

$ make
...
[INFO] Starting the development server...
...
[ERROR] Error: Processing of blog source file path=2000-10-30-my-blog-example/index.md failed.
    at doProcessBlogSourceFile (/Users/dariusn/dev/dn/git/Beman/website/node_modules/@docusaurus/plugin-content-blog/lib/blogUtils.js:268:19)
    at async Promise.all (index 0)
    ... 10 lines matching cause stack trace ...
    at async file:///Users/dariusn/dev/dn/git/Beman/website/node_modules/@docusaurus/core/bin/docusaurus.mjs:44:3 {
  [cause]: Error: Blog author with key "neatudarius" not found in the authors map file.
  Valid author keys are:
  - JeffGarland
  - dabrahams
  - DavidSankel

• Fix the error, re-deploy the local website.

• Commit and push the changes. Wait for a new CI preview deployment.

5. After you got a succesful CI preview deployment, update the PR to be ready for review and add @leads /@core-reviewers.

6. Apply the review feedback. Get approval. Merge the PR.

7. The updates are automatically deployed to the production website after a few minutes - check https://bemanproject.github.io/website/.

Local development

Install dependencies

In order to setup the project, you have to install npm, yarn and node.

$ make install

You can verify yarn is properly installed using

yarn --version

If this fails, please check manual instructions:

Dev Container instructions

This project includes a development container configuration for VS Code. To use it:

1. Install Visual Studio Code and the Dev Containers extension.
2. Open the project in VS Code.
3. When prompted, reopen the project in the dev container.
4. The container will automatically install dependencies and set up the environment.
5. Go to the Start local server section.

Linux instructions

$ sudo apt install nodejs
$ sudo apt install npm
$ npm install yarn

MacOS instructions

$ brew install node
$ brew install npm
$ npm install -g yarn

Windows instructions

$ winget install OpenJS.NodeJS
$ npm install -g yarn

Start local sever

To start a local development server, run:

$ make start

If everything is properly installed, the command should open a browser window on http://localhost:3000/.

Most changes are reflected live without having to restart the server.

Generate static content for GitHub Pages deployment

To generate static from the project that can be served using any static contents hosting service (like gh-pages).

$ make build