Code Blocks That Are Easy to Read and Write

Code is something we often revisit, modify, and test after writing it.

Contents

That's why OJapp Blog Kit does more than put code inside a dark box. It focuses on showing the language, making syntax readable with color, allowing one-click copying, and making indentation levels easy to follow.

This article explains how to write code blocks in Markdown and how Blog Kit presents them.

Start by Specifying the Language

In Markdown, write the language name immediately after the three backticks that open a code fence. The language is shown at the top of the block, and syntax highlighting is applied accordingly.

Markdown
```js
console.log("Hello, Blog Kit!");
```

The result is a JavaScript code block like this:

JavaScript
console.log("Hello, Blog Kit!");

Use Syntax Colors to Understand the Code

Colors help distinguish keywords, strings, and other parts of code. Even in longer examples, they make it easier to follow what the code does.

JavaScript
function createWelcomeMessage(name) {
  const message = `Hello, ${name}!`;
  return message;
}

const message = createWelcomeMessage("OJachi");
console.log(message);

Write the language name, such as js or javascript, right after the opening code fence. For JSON, use:

JSON
{
  "title": "My Blog",
  "language": "en",
  "writeInMarkdown": true
}

Follow Nested Code with Indentation Guides

When code contains nested blocks, it can be difficult to see which lines belong to the same level. Blog Kit displays vertical guides that follow the code's indentation.

JavaScript
function publishArticle(article) {
  if (!article.title) {
    return { ok: false, reason: "Missing title" };
  }

  return {
    ok: true,
    article: {
      title: article.title,
      published: true,
    },
  };
}

These guides are added when the code is displayed. You don't need special Markdown syntax. Just indent the code consistently, and the structure becomes visible.

Copy and Try Code Immediately

Code blocks include a copy button. Readers can copy the contents without selecting and dragging over the text.

Bash
npm install
npm run build

Only the code is copied, without display colors or borders. Paste it into a terminal or editor and use it directly.

Show Changes with Diff Blocks

When explaining a change to a setting or code snippet, specify diff to highlight added and removed lines.

Diff
- const theme = "plain";
+ const theme = "vitesse-dark";
  const readable = true;

A short diff shows exactly what changed, without making readers compare two complete versions.

HTML and CSS Work the Same Way

The code fence syntax is the same for every language. Use html for HTML and css for CSS.

HTML
<article class="post">
  <h2>Article title</h2>
  <p>This article was generated from Markdown.</p>
</article>
CSS
.post {
  max-width: 720px;
  margin-inline: auto;
  line-height: 1.9;
}

Make Your Examples Easier to Understand

Readability also depends on what you choose to show, not just how the code looks.

Blog Kit intentionally does not show line numbers. The goal is to help readers focus on the code itself and its indentation, rather than tracking line numbers.

Keep Using Standard Markdown

Code blocks use ordinary Markdown code fences. You don't need to learn Blog Kit-specific syntax or embed HTML in your articles.

Markdown
```js
const blog = "Publish on your own domain";
```

Your source articles remain plain Markdown files. Blog Kit handles their presentation so you can focus on the content.

Code examples should be easy to read and easy to try. That's another part of building a blog where writing comes first.

Compare Shiki Themes Side by Side

Blog Kit uses Shiki for syntax highlighting. The examples below show the same JavaScript code rendered in different themes. Each header displays the theme name. On mobile, the comparison stays in two columns; scroll inside a code block if needed.

github-dark
const blog = "OJapp Blog Kit";
const enabled = true;
console.log(blog, enabled);
dracula
const blog = "OJapp Blog Kit";
const enabled = true;
console.log(blog, enabled);
nord
const blog = "OJapp Blog Kit";
const enabled = true;
console.log(blog, enabled);
material-theme
const blog = "OJapp Blog Kit";
const enabled = true;
console.log(blog, enabled);
one-dark-pro
const blog = "OJapp Blog Kit";
const enabled = true;
console.log(blog, enabled);
vitesse-dark
const blog = "OJapp Blog Kit";
const enabled = true;
console.log(blog, enabled);
github-light
const blog = "OJapp Blog Kit";
const enabled = true;
console.log(blog, enabled);
catppuccin-mocha
const blog = "OJapp Blog Kit";
const enabled = true;
console.log(blog, enabled);

Change the Default Shiki Theme

Add shiki_theme to site.json to change the default theme for code blocks across your site.

JSON
{
  "shiki_theme": "github-dark"
}

The setting takes effect on the next build. If omitted, Blog Kit uses its built-in default theme. To override just one block, specify theme= after the language name.

Markdown
```js theme=dracula
console.log("Hello, Blog Kit!");
```

Compare Code in Two Columns

Use :::code-grid to place code blocks side by side. You can also set custom header labels with title=, such as Original and Diff.

Markdown
:::code-grid
```js title=Original
const theme = "github-dark";
```

```diff title=Diff
- const theme = "plain";
+ const theme = "github-dark";
```
:::
Original
const theme = "github-dark";
Diff
- const theme = "plain";
+ const theme = "github-dark";

Welcome to OJapp Blog Kit

OJapp Blog Kit is a lightweight static blog engine for writing articles in Markdown and publishing them on your own domain.

OJapp

← Back to articles