Skip to content
JournalTORIS / FIELD NOTES

← Blog Project notes

[Case Study] Toris Blog: How We Built Our Own Company's Tech Blog

A dogfooding case study of the technical decisions and file-based CMS trade-offs Toris made while designing, building, and running its own tech blog.

10 min read Read the Korean original

Joohwan Yu · Founder, Full Stack Developer

Toris · Published

Contents

Q. Why did we build the company tech blog ourselves instead of using an off-the-shelf platform? To use the blog itself as both a portfolio and a technical testbed, we built it directly on our main stack, Next.js, with a file-based CMS (MDX + Git).

Product name: Toris Blog First built: 2024.03 (still being improved) Tech stack: Next.js, TypeScript, Tailwind CSS, MDX, Vercel, GitHub Actions Positioning: Toris’s official tech blog, and a permanent testbed for our own tech stack

The blog this post appears on is the subject of this case study. Toris Blog is our own media property, which Toris designs, builds, and runs directly, without outsourcing or an off-the-shelf platform. We build our site with the same stack we use for client products, then take the patterns proven here back into products. It is a classic dogfooding structure. This post records the technical decisions made in that first build and the trade-offs that surfaced while running it.

Summary of key decisions

DecisionChoiceTrade-off
Content storeFile-based CMS (MDX + Git)Gave up dynamic content and bulk management; gained zero infrastructure cost and Git history
Code highlightingReplaced highlight.js with shikiGave up runtime highlighting; gained editor-grade quality and build-time processing
Navigation stateURL parameters as the source of stateTraded the simplicity of component-internal state for shareable links and history
ThemeCSS-variable-based switching + localStorage persistenceRequires the discipline of never referencing color values directly; simplifies switching logic
DeploymentVercel + GitHub Actions auto-deployUp-front environment setup cost; afterwards no publishing friction and a build-time safety net

1. Problem definition and product hypothesis

For a software studio, a tech blog solves two problems at once. First, knowledge gained from projects gets trapped in personal notes (Notion at the time) and evaporates; knowledge that isn’t organized isn’t reused. Second, there was no public place to show “what this studio builds and how.”

Using an off-the-shelf blogging platform was an option. But we went the other way.

“The most honest way to show how we build is to build our own site with our own hands.”

The blog itself becomes both a portfolio and a technical proving ground. Before applying new framework features, rendering strategies, and SEO techniques to client products, we run them here first. Since the blast radius of a failure is contained to ourselves, our own blog is the cheapest experimental environment.

Advertisement

2. Constraints

  • Solo operation: The writer, the developer, and the operator are the same person. Unless the structure has low maintenance cost, the blog gets abandoned.
  • Minimal infrastructure budget: There is no reason to burn fixed server costs on our own media. Paid infrastructure such as databases and managed CMSs is ruled out until its value is proven.
  • A workflow where content is code: If writing is separated from the development workflow (editor, Git, PR), there is friction in moving between two tools.
  • Dependence on search traffic: Most visitors arrive via search. SEO is not an add-on feature but a survival condition for the media property.

3. Technical design and trade-offs

3.1 Stack choice: Next.js + TypeScript + Tailwind

We chose Next.js as the framework, for three reasons. First, a blog is inherently static content, so hybrid rendering, where static generation (SSG) and server-side rendering can be chosen per page, fits well. Second, file-based routing naturally aligns content structure with URL structure. Third, it is Toris’s main stack: for the purpose of dogfooding, the blog only means something if it is built with the same technology we use for products.

Drawing the boundary between server components and client components had an initial learning cost, but the discipline of drawing that boundary explicitly carried over into the design sense of later projects. Knowing the areas the framework handles for you, such as the Image component’s automatic image optimization, was also important in deciding “what not to build ourselves.”

TypeScript’s type definitions looked like a cost at first, but soon became the single source of truth for the content schema.

interface Post {
  title: string;
  content: string;
  date: string;
}

const posts: Post[] = getPosts();

The Post interface enforces the frontmatter convention in code. When a field changes, the compiler points out the entire blast radius. In a solo operation, the compiler effectively doubles as a code reviewer. More accurate IDE autocompletion is a bonus.

3.2 File-based CMS: the central trade-off of this project

The biggest architectural decision was the content store. Instead of a managed CMS or a database, we chose a file-based CMS that keeps Markdown (MDX) files as-is in a Git repository.

AspectFile-based (chosen)DB/managed CMS (rejected)
Infrastructure cost0: the repository is the CMSDB hosting or CMS subscription
Version controlGit history comes freeMust be implemented separately
Authoring workflowSame as code (editor → commit → PR)A separate admin screen
Failure pointsNone (made static at build time)The DB is a single point of failure
Dynamic contentHardEasy
Bulk managementBurdensome as files growFavorable at scale

The advantages of the rejected alternative, dynamic content and bulk management, are real costs. As files multiply, management gets harder, and dynamic features such as comments can’t be solved with files alone. We made this choice anyway because of the shape of whoever runs the blog. In a one-person studio, the equation “writing = a commit” minimizes the friction of publishing. Fixing a typo and doing a large overhaul both go through the same PR workflow. The fact that Git provides review, rollback, and history tracking for content for free was worth more than any convenience feature of a separate CMS.

This decision has held up so far, with one condition: we revisit it when the point of “when files multiply” arrives. Architectural decisions have an expiration date, and I believe that stating it explicitly is part of the design.

3.3 Rendering pipeline: replacing the code highlighter

The quality of a tech blog’s body text is decided by its code blocks. We started with highlight.js but replaced it with shiki during operation. The reason for the replacement is rendering quality: shiki provides highlighting based on editor-grade syntax analysis, and since it is processed at build time, the client-side burden is also cleaned up. We also designed theme support for each of dark and light modes.

This replacement gave us an operational insight. The performance implications of a library choice, like the loading cost of large code blocks, show up not at adoption time but after the content has accumulated. Because it was our own blog, we could experiment with the replacement without pressure, and this kind of “swap during operation” experience is the real return on dogfooding.

3.4 Theme system

Dark mode is implemented with CSS-variable-based theme switching. If components don’t know color values directly and only reference variables, switching themes simplifies to swapping the variable set at the root.

const [theme, setTheme] = useState('light');

const toggleTheme = () => {
  const newTheme = theme === 'light' ? 'dark' : 'light';
  setTheme(newTheme);
  localStorage.setItem('theme', newTheme); // persist across revisits
};

The user’s choice is stored in localStorage and persists across revisits, and system theme detection sets the initial value. It’s a small feature, but it is a miniature of the principle of “respecting the user’s environment settings,” and this pattern was carried over unchanged to Toris’s other products.

3.5 Navigation structure: the URL as the source of state

For category and tag filters, we designed URL parameters, not component-internal state, as the source of state. When parameters are managed with Next.js’s useRouter, a filtered screen becomes a shareable link, and the back button works naturally. The filtering logic was split into a custom hook and reused across list screens. This principle, “put shareable screen state in the URL,” also became the default in later projects.

3.6 SEO: essential design for a media property that lives on search traffic

The blog’s distribution channel is search. So we structured SEO in three layers.

  • Metadata layer: Generate title/description per page with generateMetadata, and manage how it displays when shared on social media with Open Graph tags.
  • Structured data: Convey the semantic structure of the content to search engines with JSON-LD.
  • Crawling support: Generate a sitemap to state the indexing paths explicitly.
export async function generateMetadata({ params }) {
  return {
    title: post.title,
    description: post.description,
    openGraph: {
      title: post.title,
      description: post.description,
      images: [post.image]
    }
  };
}

File-based CMS and SEO go well together. Since the frontmatter is the source of the metadata, the act of writing automatically generates SEO data. There is no need for a separate “SEO input screen.”

3.7 Deployment pipeline

Deployment is a combination of Vercel + GitHub Actions. It’s a pipeline where pushing to the main branch automatically builds and deploys, so content publishing and code deployment take the same path. In this structure, a build failure acts as a pre-deployment line of defense: the pipeline stops broken frontmatter or type errors before they reach production. Environment variable management and handling build errors cost something up front, but once in place, publishing friction virtually disappeared.

4. Validation with readers and users

The feedback loop of our own blog has two layers: the loop from readers, and the dogfooding loop in which we ourselves are the first users.

4.1 The first user is ourselves

This is the essence of dogfooding. Every time we write, we use this blog’s authoring experience (authoring UX), and any inconvenience immediately becomes backlog. Replacing code highlighting from highlight.js with shiki happened because we, as both readers and authors, weren’t satisfied with the rendering quality, and splitting the filter hook into a reusable piece happened because we felt the repetitive work as we added more screens. For a product where the distance between user and developer is zero, the speed of incorporating feedback is the speed of development.

4.2 Search engines and the social graph are users too

The paths by which readers reach the blog, search results and social share cards, are themselves subjects of validation. Whether the share preview displays correctly after setting up Open Graph, and whether structured data is interpreted correctly by search engines, are items that must be checked in the real channels after deployment. Running this blog taught me that the responsibility of a content system extends beyond “done once published” to “how it looks in the distribution path.”

4.3 A still-thin loop: direct conversation with readers

To record it honestly, a direct feedback channel from readers (comments, etc.) was not included in the scope of the first build, because dynamic features in a file-based architecture need separate design. Comments and search are managed as explicit roadmap items, which is also why this blog is a continuously improving project.

5. Operation and results

Toris Blog has been running since its first build in March 2024, and is the longest-lived product at Toris (toris.kr/blog). Dark mode, shiki-based code highlighting, category/tag navigation, three-layer SEO, the file-based CMS, and the automatic deployment pipeline are its current skeleton.

We also manage technical debt transparently.

  • No tests: We didn’t write test code in the first build. At the time it was a priority call, but I later felt that in a continuously improving project, the absence of regression safeguards eats away at the speed of improvement.
  • Accessibility: Keyboard navigation and screen reader support were left out of the initial design. This is a standard a public media property should meet, and it is something to fix.
  • Performance: Stronger image optimization, more code splitting, and removing unnecessary re-renders are ongoing improvement items.

This debt list itself is a product of dogfooding. Based on the cost of the debt we experienced on our own site, we changed our process so that client projects include tests and accessibility in the scope of the first build.

6. Reusable lessons

  1. The shape of whoever runs it determines the architecture. In a solo operation, a file-based CMS where “writing = a commit” beats the feature list of a managed CMS. Architecture comparison tables must be read on top of the team structure.
  2. Put an expiration date on architectural decisions. The file-based CMS is a conditional decision: “until content grows to large volume.” Stating the trigger for revisiting is part of the design.
  3. Put shareable screen state in the URL. If you manage filter and navigation state with URL parameters, link sharing and browser history come free.
  4. A content system’s responsibility extends to the distribution path. The entire pipeline running from frontmatter to metadata to search/social display is the product.
  5. Your own service is the cheapest testbed. Library swaps (highlight.js → shiki), rendering strategies, and the theme system are validated here first and then taken to products. And we measure the cost of the debt incurred here (tests, accessibility) and use it as the basis for changing the first-build scope of the next project.

Advertisement