How to write articles

Prerequisites

• You have a text editor installed
• You will need git and know how to use it.
• You have access to our gitlab: Gitlab access
• You have permissions in the project containers/documentation
• You will need a recent version of nodejs and npm (Install from here)

Quick Start

• Clone the repository

• add your article as md file to markdown/article, or edit a existing article

• Run npm run dev and preview the app in your browser at http://localhost:3000.

• Commit your changes.

• Run npm version patch to increment the version number.

• Push the repo, including it's tags. Run either

    git push --follow-tags
  

  or make tag pushing the default in your git config with

    git config --global push.followTags true
  

• The CI will only trigger for tagged commits.

• Check if the CI completed successfully here

• If you have kubernetes access you can deploy the application. Run update.sh in the kubernetes folder.

Basics

All articles here are written in Markdown, a very simple plain text format.

E.g. the above paragraf is written in markdown and looks like this in it's plain text format:

### Basics

All articles here are written in
[Markdown](https://www.markdownguide.org/cheat-sheet/), a very simple plain text format.

Articles are in the folder markdown/articles/ creating a new markdown file there will automatically create the article.

Metadata

We use a markdown extension to provide metadata to the application in a format called frontmatter.

At the beginning of the markdown file please provide a metadata section in this yaml format:

---
  title: How to write articles
  author:
    name: Michael Huttner
  isPublic: true
---

• title is the title listed in the Sidebar of the app
• author is author of the article
• isPublic set this to true if anyone should be able to read the article, if false only logged in users can read it.

Linking

• To link to another article use the basename of the markdown file name in a markdown link.

  E.g.

    [How to write articles](how-to-write-articles)
  

  becomes How to write articles.

• If you want to link a document put it in the protected folder (e.g. protected/documents/my_document.pdf). Then link it using

  [my document](/api/download/documents/my_document.pdf)

(i.e., you replace protected with /api/download in the file link).

Fancy Stuff

We use Tailwind to style this markdown. If you want more advanced styling options in your Markdown you can write html with tailwind classes.

For example:

<span className="p-5 text-2xl text-teal-600"> Fancy Text </span>

becomes
Fancy Text

Important documentation:

• Colors
• Font Size

Github flavored markdown

We also support Github flavored markdown features such as

• Footnotes ¹
• Tables
• Task Lists
• Strike through

Check the Cheet Sheet for more details.

Deployment Details

• This is a Next.js application inside an OCI container.
• The frontend in written in React and we use MDX to render the markdown as React Components
• We use the .gitlab-ci file to build an OCI Container from the Dockerfile also in the repository.
• This container gets tagged with the current version number and uploaded to the gitlab container registry.
• The Dockerfile is based on the Next.js Docs
• This container is deployed to our Kubernetes Cluster
• All the files necessary for the deployment are in the kubernetes folder.