🗒️

エンジニアなら自分でブログを作れ!②テンプレ理解編

2022/09/28に公開

初めに

この記事は「エンジニアなら自分でブログを作れ!」の第二弾です。
第一弾を読んでいなくても問題ありませんが、第一弾では無料の自作ブログを作成するために必要な導入について解説しているので良ければご覧ください。

第一弾↓

https://zenn.dev/miketako3/articles/9b2b1a9ec13901

この記事はNext.jsの
blog-starter
(公式のデモページ)
について、自作ブログをカスタマイズする上で必要そうなファイルや知識について解説します。

前提知識

この記事では前提知識として以下が必要です。

技術 どんな技術? レベル
TypeScript Microsoftが開発したJavaScriptに型を追加した言語 文法を理解している。
React Facebookが開発したフロントエンドフレームワーク コンポーネントを読み書きできる。
Next.js Vercelが開発したReactベースのフレームワーク 勉強する気がある。
Tailwind CSS ユーティリティファーストのCSSフレームワーク クラス名を自分で調べられる。

つまり、TypeScriptとReactの知識、そしてやる気があれば大丈夫です。

それらについても深い知識はいらないはずですが、それすら無い人はサクッと勉強しましょう。

https://typescript-jp.gitbook.io/deep-dive/

https://ja.reactjs.org/tutorial/tutorial.html

用語

blog-starterで使われている用語について、初見でわからなそうなものを列挙しておきます。

用語 意味
slug 記事につけるIDのこと。_postsディレクトリに${slug}.mdという名前で記事を作成する。
excerpt 記事の要約のこと
hero トップページの最初に出てくる大きく表示される記事のこと

前提知識に無い技術の解説

Next.js

Next.jsについて最初に覚えておくべきことをまとめます。

ルーティング

https://nextjs-ja-translation-docs.vercel.app/docs/routing/introduction

pages ディレクトリ以下のディレクトリ構成がそのままルーティングになります。

pages/posts/[slug].tsx というファイルがありますが、これは ${ドメイン}/posts/${slug} というURLに対応しています。

特別な関数

getStaticPaths()getStaticProps() という関数が pages 以下のtsxファイルに実装されています。

これらは特別な関数で、ルーティングやページを生成するデータを取得するために必要です。

getStaticPaths()

https://nextjs-ja-translation-docs.vercel.app/docs/basic-features/data-fetching/get-static-paths

pages/posts/[slug].tsx では以下のように実装されています。

export async function getStaticPaths() {
  const posts = getAllPosts(['slug'])

  return {
    paths: posts.map((post) => {
      return {
        params: {
          slug: post.slug,
        },
      }
    }),
    fallback: false,
  }
}

これは _posts ディレクトリ以下のslugを全て抜き出して整形して返す関数となっていて、ここで返されるパスだけが表示されます。

逆に言えば _posts 以下に存在しないslugをパスに入れると404になります。

getStaticProps()

https://nextjs-ja-translation-docs.vercel.app/docs/basic-features/data-fetching/get-static-props

こちらも pages/posts/[slug].tsx では以下のように実装されています。

export async function getStaticProps({params}: Params) {
  const post = getPostBySlug(params.slug, [
    'title',
    'date',
    'slug',
    'author',
    'content',
    'ogImage',
    'coverImage',
  ])
  const content = await markdownToHtml(post.content || '')

  return {
    props: {
      post: {
        ...post,
        content,
      },
    },
  }
}

getStaticProps() ではパスが指定された時にReactコンポーネントに渡す引数を生成していています。

blog-starterのコードでは、パスのslugからメタデータとmarkdownの内容を取ってきて、markdown部分をhtmlに変換し、Reactに渡す引数として整形して返しています。

Tailwind CSS

Tailwind CSSでは多量のクラス定義が提供され、それらのクラスをつけるだけでコンポーネントのデザインを変更できます。

例えばクラスに mb-12を追加すると、これはmargin-bottom: 12の略になっていて、追加された要素の下側に余白が追加されることになります。

https://tailwindcss.com/docs/margin

他にも色々なクラスがあるのでわからなくなったら公式サイトをチェックしましょう。

https://tailwindcss.com/docs

blog-starterのtsxファイルのclassNameで指定されている部分の大半はTailwind CSS由来のものなので、とりあえずここで探すのが良いです。

blog-starterのディレクトリ構成

blog-starterのディレクトリ構成としては以下のようになっています。

.
├── @types
├── _posts
├── components
├── interfaces
├── lib
├── node_modules
├── package.json
├── pages
├── public
├── styles

このうち @types, node_modules, package.json
の3つはNode.jsやTypeScriptに共通のため省略し、それ以外のディレクトリについて解説していきます。

_posts

ブログ記事はどこに書くのかというと、この _posts ディレクトリ以下にMarkdownで書きます。

blog-starterでは多数のメタデータ ( coverImage とか) がありますが、当然変更可能です。
メタデータは他の部分でも利用されているので、それらを変更してからMarkdownの方を変更しましょう。

components

Reactのコンポーネントが定義されています。これらのコンポーネントを組み合わせて pages 以下の各ページが作られています。

interfaces

記事データの型が定義されています。記事で使うメタデータを変更したい時はまずはここから変更しましょう。

lib

Reactではない (tsxファイルでは無い) ファイルが配置されています。このディレクトリはファイルごとに解説します。

markdownToHtml.ts

markdownをhtmlに変換する関数が実装されています。

ほぼremark-htmlというライブラリを使うだけになっていて、全くリッチなhtmlにはなりません。

技術ブログを書くのであればコードのシンタックスハイライト等が欲しいと思うので、一番最初にカスタマイズしたいところです。

constants.ts

定数が定義されています。

色々な場所で使われてはいるが、正直個人ブログで定数を外出しするメリットはあまり無いと思っています。

大したものは定義されていないので、利用箇所を先にカスタマイズしていらなくなったら消してしまいましょう。

api.ts

バックエンド的な意味合いで、Reactコンポーネントで使うために記事データを引っ張ってくる関数が定義されています。

中身としては _posts 以下のファイル名や中身を読んで返しているだけなので、リッチなブログにしたい場合はここもカスタマイズしたいところです。

例えばここでローカルのファイルからではなく外部CMSのAPIから取ってくるようにすれば、 JAMStack構成のブログが完成します。

https://blog.microcms.io/jamstack-introduction/

pages

ページ単位のReactコンポーネントが実装されています。ブログに記事以外のページを増やしたい時はここから増やしましょう。

blog-starterではトップページと記事ページの2種類が実装されています。

public

そのまま公開するものがこのディレクトリには入っています。記事に使う画像等もここに入れる想定になっています。

また、faviconもここに入っています。ブログのアイコンになる部分なのでここも是非カスタマイズしたいですね。

styles

全体に適用するCSSが配置されています。

blog-starterではTailwind CSSの読み込みのみが定義されていて、デザインでTailwind CSSのみを使うのであれば弄ることはないでしょう。

まとめ

この記事ではNext.jsのblog-starterで自作ブログを作る上で必要そうなファイルや知識について解説しました。

次回以降はいよいよカスタム機能を実装していきたく、次のような内容を考えています。

  • デザインをZenn風にしてみる。
  • 独自ドメインを付ける。
  • タグ機能を実装する。
  • 記事一覧をページングする。
  • おすすめ記事を実装する。
  • Micro CMSでJAMStack構成にしてみる。

それぞれ記事公開には時間がかかるとは思いますが、やる気があるエンジニアであれば現状の知識だけでも十分好きな機能を実装できるでしょう。

色々試してみてください。

最後に、私の投稿はZenn以外の投稿もまとめて以下ブログで取得できますので、良ければ見てみてください。

https://blog.miketako.xyz

追記

次回

https://zenn.dev/miketako3/articles/66e1cc17193168

Discussion