Dev Dungeon

FULLHAUS DEV DUNGEON is a monthly-ish dev huddle for updates on the FULLHAUS tech stack, team related stuff, for building team culture and promoting exchange among the team.

Each meeting contains a presentation where all discussed themes are summarized. Usually those won't go in depth therefore, we also got a blog formatted Dungeon which is intended to go in depth.

How to Dev Dungeon

If you got a topic you would like to talk about you should first check if someone else is already talking about this topic, usually you can hit up David and ask him.

1. Create a branch

If there is already a Dev Dungeon branch then create a new branch from there and commit to this branch. Otherwise, create a branch named feature/dev-dungeon-<count> whereas <count> is the index of the upcoming Dev Dungeon (e.g. feature/dev-dungeon-4). Then delete anything from the old Dev Dungeon and add your topic.

2. Create a presentation slide

As you are going to present your topic to the team, you will need to create a presentation slide for that. To do so create a file in src/pages/dungeon-reveal/slides named after your topic with Slide as suffix e.g. MyTopicSlide.tsx.

Then create a component named like the file. Using the example from above this would look like this:

src/pages/dungeon-reveal/slides/MyTopicSlide.tsx
export default function MyTopicSlide() {
  return (
    <section>
      Hello Slide!
    </section>
  );
}

Then add this slide to the presentation page by importing it in src/pages/dungeon-reveal/index.tsx:

src/pages/dungeon-reveal/index.tsx
// ...

import Intro from '@site/src/pages/dungeon-reveal/slides/Intro';
import MyTopicSlide from '@site/src/pages/dungeon-reveal/slides/MyTopicSlide';

export default function DungeonRevealPage() {
  // ...

  return (
    <Layout noFooter>
      <main style={{
        blockSize: revealMountHeight,
      }}>
        <div className="reveal" ref={deckDivRef}>
          <div className="slides">
            <Intro />
            <MyTopicSlide />
          </div>
        </div>
      </main>
    </Layout>
  );
}

If you now go to http://localhost:3000/dungeon-reveal your slide should be visible.

You can read up on how to create a slide on https://revealjs.com/markup/ but keep in mind that not everything will work as expected due to the implementation to Docusaurus which is not natively supported. This results in some weird quirks. For example: Code blocks should be used with the Docusaurus component <CodeBlock> and need to be early returned in order to pass SSG.

SlideOne.tsx
export default function SlideOne() {
    // early return if using <CodeBlock>
    if (!useIsBrowser()) return;

    return (
        <CodeBlock>
            {`
console.log('Hello weird quirks!');
`}
        </CodeBlock>
    );
}

3. Create a blog entry

The blog entry is very useful for people who missed the Dev Dungeon. Therefore, blog entries should be in depth and not as short as its presentation slide.

You can create a blog entry (if there is none yet) in the dev-dungeon directory. Just create a file named <yyyy-mm-dd>-vol-<count>.md(x) where:

<yyyy-mm-dd> stands for the date where the Dev Dungeon will take on
<count> stands for the index of this Dev Dungeon
the file can be either .md or .mdx

e.g. 2024-06-13-vol-3.mdx

Before you start editing this file you should check the metadata. If it's your first contribution to this file you should add yourself to the authors array and add an appropriate tag to the tags array.

dev-dungeon/yyyy-mm-dd-vol-3.md(x)
---
slug: vol-3
title: VOL. III
authors:
    - key: eddy
      title: How to Dev Dungeon
tags: [HowTo]
---

authors
- key: are referenced in dev-dungeon/authors.yaml
- title: the titles of your blog post-entries
tags: can be anything but should be more generic

A Dungeon Blog is usually structured like this:

Dev Dungeon cover image
A short agenda (followed by the truncation )
All topics where each topic got a h2 (##) heading
A Dungeon Pick which can be an interesting article, blog post, video or personal advice

Create a topic

Create a markdown file (or mdx) inside dev-dungeon/dungeon/vol-x whereas x is the index of the Dev Dungeon. The file should start with an underscore (_, this indicates that this file will be used like a component) and be named after your topic in kebab-case. Please start the file with a ## followed by the title of your topic. Now you can just start writing your blog post about your topic! You should check out the Docusaurus documentation to get the full potential out.

dev-dungeon/dungeon/vol-3/_my-topic.mdx
## My topic
Today I'm gonna talk about `Hello World`

warning

Do not use ## a second time inside that file as this would create a new topic in the sidebar and might lead to confusion!

Add your topic to the blog post

To add your topic to the actual blog you will need to import your topic inside the yyyy-mm-dd-vol-x.md(x) file. You can do so by importing your just created topic and consume it like a component. Don't forget to add your topic to the agenda as well!

dev-dungeon/yyyy-mm-dd-vol-3.mdx
---
slug: vol-3
title: VOL. III
authors:
    - key: eddy
      title: How to Dev Dungeon
tags: [HowTo]
---

import MyTopic from './dungeon/vol-3/_my-topic.mdx';
import AnotherTopic from './dungeon/vol-3/_another-topic.mdx';

![FULLHAUS DEV DUNGEON](/dev-dungeon/fullhaus-dev-dungeon-vol-III.png)

- My Topic
- Another Topic

<!--truncate-->

<MyTopic />
<AnotherTopic />

4. After the dungeon

After your presentation there might be some corrections or supplementary topics. Please add those to the blog as well before the Dev Dungeon branch gets merged.

File handling

If you would like to add some assets, you should do that by uploading your asset to the server or ask Edwin to do that for you.

After it's uploaded you can consume it by using the <AssetsImage /> component.

MyTopicSlide.tsx
import AssetsImage from '@site/src/components/AssetsImage';

export default function MyTopicSlide() {
    return (
        <section>
            <AssetsImage src="/path/to/your/asset.svg" />
        </section>
    );
}

important

You need to be connected to the fullHaus VPN or the in-house network as those images are only reachable this way.

Why not put assets into the repo?

Tracking binary files with git will influence the performance of git in a bad way and bloat the repository unnecessary. Especially for sections like the Dev Dungeon where assets might change a lot this will become contra productive.

How to Dev Dungeon​

1. Create a branch​

2. Create a presentation slide​

3. Create a blog entry​

Create a topic​

Add your topic to the blog post​

4. After the dungeon​

File handling​