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.
comments: true                # If comments should be enabled for this blog post. Default: true.
---

# 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.

Note: The Discourse comments plugin only works for production website (a.k.a. https://bemanproject.org/). You cannot test it locally or on preview deployments. Check Integrate Discourse comment feature for blog posts for more details.

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 CONTRIBUTING.md) 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/.

Development

Local setup, dependencies, and running the site: see CONTRIBUTING.md.