# はじめに

ブログに数式の表示機能を実装した。そのうち統計学や機械学習の数理も勉強して記事にできればなと漠然と思っているのでその下準備的な意味も込めて。自分は以前 [`MathJax`](https://www.mathjax.org/) を使ったことがあったけれど、今回改めて調べてみると以下のような情報があった。

<blockquote class="twitter-tweet"><p lang="ja" dir="ltr">mathjax というやつは世の中に現存するJSの中でも最も行儀が悪い振る舞いをするものの一つです。気軽に導入していいものではない。というか積極的に避けねばならない。あいつはXML的木構造を破壊しながら自身の特殊構文に継ぎ直してる。</p>&mdash; mizchi (@mizchi) <a href="https://twitter.com/mizchi/status/856772057543057408?ref_src=twsrc%5Etfw">April 25, 2017</a></blockquote>

<blockquote class="twitter-tweet"><p lang="ja" dir="ltr">一度mathjaxを当てた箇所は真っ当なフレームワークのDOMレンダリングに回復することは不可能です</p>&mdash; mizchi (@mizchi) <a href="https://twitter.com/mizchi/status/856772327354146816?ref_src=twsrc%5Etfw">April 25, 2017</a></blockquote>

ということで今回は [`KaTeX`](https://katex.org/) を使うことにした。前に記事にしたように、このブログはContentfulにmarkdownの形で記事データを持っており、クライアントでそれをHTMLにマークアップしている。KaTeXはmarkedの `renderer` の中で使うことになる。

> info:記事作成時の環境について
> 
> - `marked`: 2.0.5
> - `katex`: 0.13.11
> - `next`: 10.2.2 (今回 Next.js は全く関係ないが一応記載)

# 実装について
## 参考にした情報
実装は次のリンク先のコメントで共有されている方法にまるまる乗っかっているので、コードは省略する。

https://github.com/markedjs/marked/issues/1538#issuecomment-526189561

この方法に乗っかると以下のような書き味になる。

- インラインの数式を使いたい時はインラインコードの中で対象を `$` で囲う
- ブロックの数式を使いたい時はコードブロックの中で対象を `$$` で囲う

## 注意点
### CSSを読み込んでおく
そもそもの話だけど、KaTeXを使う場合KaTeXのCSSを読み込む必要があるので、以下のスクリプトタグを書いておく。Next.jsなら `_document.tsx` の `<Head>` 内に書くことになる。

```html
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/katex@0.13.11/dist/katex.css"
  integrity="sha384-knaESGLxlQRSHWSJ+ZbTX6/L1bJZWBsBYGb2O+g64XHFuO7CbIj9Pkf1aaVXzIZJ"
  crossOrigin="anonymous"
/>
```

### サニタイズに気をつける
KaTeXで生成したHTMLには `<span>` タグの中に、`class` や `style` などのAttributeが存在している。このブログではmarkedでマークアップしたHTMLを自前でサニタイズをしているので、設定によってはここで上記のAttributeが落ちる。サニタイズを行っていない場合は全く気にすることはないけど、サニタイズをしていて表示が崩れている場合はサニタイザーの設定を疑うと良い。

# 結果のサンプル

量子力学では状態の時間発展はSchrödinger方程式に従う。
```
$$i\hbar\frac{\partial}{\partial t}|\psi, t\rangle=\hat{H}|\psi, t\rangle$$
```
ここで `$\hat{H}$` はハミルトニアン演算子で全体のエネルギーを表す。スピンのない非相対論的で外力の働いていない粒子の運動を考えると、ハミルトニアンは次式で書ける。
```
$$\hat{H} = \frac{1}{2m}\hat{\bm{p}}^2$$
```
ここで `$m$` は粒子の質量であり、`$\hat{\bm{p}}$` は運動量演算子である。位置基底で考えるとSchrödinger方程式は次式になる。
```
$$i\hbar\frac{\partial}{\partial t}\psi(\bm{x}, t)=-\frac{\hbar^2}{2m}\nabla^2\psi(\bm{x}, t)$$
```
`$\psi(\bm{x}, t)=\langle\bm{x}|\psi, t\rangle$` は位置空間での波動関数である。

ということで、良い感じになった。

Next.js, Contentful, markedの環境における数式表示

# はじめに
https://silurus.dev/articles/6qI4Ldg0VRdQJXDfxlqElf

一般的なブログサービスやQiita、Zennといったサービスでは、Markdownに記述した外部リンクがカード的なUIで表示されることがある。これは OGP (Open Graph Protocol) という仕組みを使った表現で、単なるテキストリンクよりもずっと見栄えがいいのでこのブログでも実現したいと思っていた。先日試行錯誤してひとまず形になったので、この記事ではその実装の方法についてまとめておきたいと思う。上に貼り付けたこのブログ自身へのリンクがそれにあたる。

> info:このサイトのフロントエンドの技術スタック
> 
> - `Next.js` （ブログ記事のSSGに使用）
> - `marked` （Markdownのマークアップに使用）
> - `Material UI` (スタイリングに使用）

# Markdownの何をカードに変換するか
`marked` でMarkdownをHTMLにマークアップするとき、まず何も考えずに変換するとMarkdownのリンクはすべて `<a>` タグのHTMLに変換される。いまやりたいことは、このうち `URL !== innerText` のリンクをカードに置き換えることである。つまり、Markdownで言えば、`[text](https://www.sample.com)` で書かれるリンクは通常通りテキストリンクとして残し、`https://www.sample.com` のようなベタ置きのURLをカードに変換するということになる。

## OGPでデータを取得するタイミング
現状、ブログ記事のReactコンポーネントは `getStaticProps` でCMSから取得したMarkdown (つまり文字列) をPropsで受け取り、コンポーネント内部で `marked` によってHTMLにマークアップしている。Markdown内に現れるリンクは各記事に依存するが、SSGする場合、コンポーネント内の副作用で外部と通信してリンク先情報を取得、はできないので、リンク先情報についても記事同様 `getStaticProps` で事前に取得し、Props経由でコンポーネントに渡す必要がある。

## リンクをカードに差し替えるタイミング
これは2つ考えられる。`marked` でリンクのカスタム `renderer` を定義し、適宜リンクをカードにマークアップする方法と、一旦HTMLでレンダリングしてしまった上で、副作用により対象の `<a>` タグをカードに差し替える方法である。今回は前者で実装した。なお、この方法でカスタム `renderer`を定義する場合は、URLのサニタイズに注意を払う必要がある。 `marked` のデフォルト `renderer` はそこをよしなにやってくれていた。

# 具体的な実装
ここからは具体的な実装について書いていく。突貫で作ったので雑なところは今後時間があるときにリファクタリングしていきたい。

## いくつかのutility関数の用意
以下の関数はコンポーネントの中に書くと長くなるので外に切り出した。

### リンク先情報の取得
今回OGPクライアントとして以下を使用している。

https://www.npmjs.com/package/open-graph-scraper

このOGPクライアントを使用してリンク先情報を取得する処理は以下の関数にまとめた。URLの配列を受け取り、OGPで取得したリンク先情報の配列を返す。

```typescript:getOgpData.ts
import openGraphScraper, {
  OpenGraphImage,
  OpenGraphProperties,
} from 'open-graph-scraper';

export type OgpData = OpenGraphProperties & {
  ogImage?: OpenGraphImage | OpenGraphImage[] | undefined;
};

const getOgpData = async (floatingUrls: string[]): Promise<OgpData[]> => {
  const ogpDatas: OgpData[] = [];
  if (floatingUrls.length === 0) return ogpDatas;

  await Promise.all(
    floatingUrls.map(async (url) => {
      const options = { url, onlyGetOpenGraphInfo: true };
      return openGraphScraper(options)
        .then((data) => {
          // OGP によるデータ取得が失敗した場合
          if (!data.result.success) {
            return;
          }
          // OGP によるデータ取得が成功した場合
          ogpDatas.push(data.result);
        })
        .catch((error) => {
          // error を throw するとビルドできないため、コンソールに出力して return する
          // eslint-disable-next-line no-console
          console.log(error);
        });
    })
  );

  return ogpDatas;
};

export default getOgpData;

```

### Markdownからベタ置きリンクの抽出
一つ前のリンク先情報取得のために、Markdownからベタ置きリンクを抽出する関数を以下のように定義した。ネーミングはさておき、テキストの紐付かないベタ置きリンクのことをfloating urlと名付けている。引数にMarkdownの文字列を突っ込むと、ベタ置きリンク (URL) が配列で帰ってくる。

```typescript:getFloatingUrls.ts
const getFloatingUrls = (md: string): string[] => {
  const regFloatUrl = /(?<!\()https?:\/\/[-_.!~*\\'()a-zA-Z0-9;\\/?:\\@&=+\\$,%#]+/g;
  const floatUrls = md.match(regFloatUrl);

  return floatUrls ?? [];
};

export default getFloatingUrls;
```

### URLからドメイン名の抽出
次の関数はリンクカード末尾にfaviconとドメインを記載するために使用する。

```typescript:getDomainFromUrl.ts
/* eslint-disable prefer-destructuring */
const getDomainFromUrl = (url: string | undefined): string | undefined => {
  if (!url) return undefined;
  let result;
  let match;
  match = url.match(/^(?:https?:\/\/)?(?:[^@\n]+@)?(?:www\.)?([^:/\n?=]+)/im);
  if (match) {
    result = match[1];
    match = result.match(/^[^.]+\.(.+\..+)$/);
    if (match) {
      result = match[1];
    }
  }
  return result;
};

export default getDomainFromUrl;
```

## ブログ記事コンポーネント
### リンク先情報の取得
記事コンポーネントの `getStaticProps` 内に、以下を追加し、取得したリンク先情報をPropsで渡すようにする。Propsの型定義などについてはこの記事では省略する。

```typescript:getStaticProps
export const getStaticProps: GetStaticProps<Props, Params> = async (
  context
) => {
   /**
   * 省略
   * ここでMarkdownの記事を取得する。
   * 記事は post (string型) とする。
   */
  const floatingUrls = getFloatingUrls(post ?? '');
  const ogpDatas = await getOgpData(floatingUrls);
  return {
    props: {
      // 略
    },
  };
};
```

### ベタ置きリンクをカードに置き換え
`marked` の `renderer` をカスタマイズして、ベタ置きのリンクをカードに置き換える。ベタ置きリンクかどうかはリンクのURLがリンクのテキストと同じかどうかで判断している。CSRF対策としてURLはサニタイズしておく必要があるので、今回は以下のライブラリを利用した。

https://www.npmjs.com/package/@braintree/sanitize-url

faviconの取得にはGoogleのAPIを利用している。また、このブログはスタイリングにMaterial UIを使っているので、CSSの中で一部Material UIのクラスを参照しているところがある。

```typescript:renderer.link
// Link の Renderer
renderer.link = (href, title, text) => {
  const sanitizedUrl = sanitizeUrl(href ?? undefined);
  const ogpData = ogpDatas.find(
    (data) => data.ogUrl && href?.startsWith(data.ogUrl)
  );

  if ((text !== href && `${text}/` !== href) || !ogpData) {
    return `
      <a href="${sanitizedUrl}" target="_blanck" 
        ${title ? `title="${title}">` : ''}
      >${text}</a>`;
  }

  const { ogImage } = ogpData;
  const image = Array.isArray(ogImage) ? ogImage[0] : ogImage;

  const domain = getDomainFromUrl(ogpData?.ogUrl);

  return `
    <div class="og-container">
      <a href=${ogpData?.ogUrl} target="_blanck" class="og-link">
        <div class="MuiPaper-root MuiPaper-outlined MuiPaper-rounded og-card">
          <div class="og-thumbnail-container">
            <img src="${image?.url}" alt="${ogpData?.ogTitle}" class="og-thumbnail"/>
          </div>
          <div class="og-text-container">
            <h1 class="og-title">${ogpData?.ogTitle}</h1>
            <p class="MuiTypography-colorTextSecondary og-description">${ogpData?.ogDescription}</p>
            <div class="og-domain-container">
              <img src="https://www.google.com/s2/u/0/favicons?domain=${domain}" alt="${domain}"/>
              <div class="og-domain-name">${domain}</div>
            </div>
          </div>
        </div>
      </a>
    </div>`;
};
```

### スタイルシート
リンクカード用のスタイルシート。Next.jsなので、以下は `_app.tsx` からimportする。

```css:og.scss
.og-container {
  .og-link {
    text-decoration: none;
    word-break: break-all;

    .og-card {
      width: 100%;
      height: 80px;
      overflow: hidden;
      display: flex;
      margin: 12px 0px;

      .og-thumbnail-container {
        position: relative;
        width: 80px;
        height: 80px;
        min-width: 80px;
        min-height: 80px;

        &::before {
          display: block;
          padding-top: 100%;
        }

        img.og-thumbnail {
          position: absolute;
          width: 100%;
          height: 100%;
          top: 0;
          right: 0;
          bottom: 0;
          left: 0;
          margin: auto;
          object-fit: cover;
        }
      }

      .og-text-container {
        width: calc(100% - 80px);
        transition: background-color 0.25s ease-in-out;
        letter-spacing: -0.15px;

        &:hover {
          background-color: rgba(128, 128, 128, 0.1);
          transition: background-color 0.25s ease-in-out;
        }

        .og-title {
          font-size: 1.1rem;
          line-height: 32px;
          margin: 4px 8px 0px 12px;
          white-space: nowrap;
          overflow: hidden;
          text-overflow: ellipsis;
        }

        .og-description {
          font-size: 0.85rem;
          line-height: 1rem;
          margin: 0px 8px 0px 12px;
          white-space: nowrap;
          overflow: hidden;
          text-overflow: ellipsis;
        }

        .og-domain-container {
          height: 1rem;
          margin: 4px;
          display: flex;
          align-items: center;
          justify-content: flex-end;

          .og-domain-name {
            display: inline-block;
            font-size: 0.85rem;
            line-height: 1rem;
            margin: 0px 4px 0px 6px;
            white-space: nowrap;
            overflow: hidden;
            text-overflow: ellipsis;
          }
        }
      }
    }
  }
}
```

以上の実装で、現状このサイトのリンクカードは実現されている。ブログを作るためにいま色々とMarkdownのマークアップ関連で実装をしているので、一段落したらまとめて公開もしたいなと思っていたり…。

OGPを使ってMarkdownのリンクをカード型のリンクにマークアップする

前の記事で少し触れたように、Contentfulでは自分で設計した `Content` に対してTypeScriptの型を自動生成してAPIクライアントに型付けすることができる。この記事ではその方法と、それを利用してコンテンツを取得し、Next.jsでSSGするまでの流れについて書きたいと思う。

> 何の装飾もない[ミニマムなブログサンプルをGitHubに公開している](https://github.com/yukiyokotani/contentful-nextjs-blog-sample)のでよかったらそちらも参考にしてください。

# TypeScriptの型を生成する
## 必要なパッケージをインストールする
- `contentful`
- `contentful-management`
- `contentful-typescript-codegen`
- `@contentful/rich-text-types`

の4つのパッケージをインストールする。ここでは `npm` を利用する。

```
npm i contentful contentful-management contentful-typescript-codegen @contentful/rich-text-types
```

`package.json` に次のnpmスクリプトを定義する。
```
"contentful-typescript-codegen": "contentful-typescript-codegen --output @types/generated/contentful.d.ts"
```

## Management APIのtokenを取得する
Contentfulの `Setting` から `API Keys` を開く。`Content management tokens` のタブを選択し、`Generate personal token` から `token` を作成する。

コピーした `token` をフロントエンドプロジェクトの環境変数ファイルにペーストする。自分の場合、プロジェクトに [`dotenv`](https://www.npmjs.com/package/dotenv) をインストールした上で `.env` ファイルを作成し、以下のような形で用意した。

```env:.env
CONTENTFUL_SPACE_ID = ****
CONTENTFUL_ENVIRONMENT = ****
CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN = ****
```

`CONTENTFUL_SPACE_ID` と `CONTENTFUL_ENVIRONMENT` は、名前の通りContentfulのスペースIDと環境名である。これらもAPIのページから確認できる。

## TypeScriptの型生成
[`contentful-typescript-codegen` の `README` に倣い](https://github.com/intercom/contentful-typescript-codegen)、プロジェクトのルートに `getContentfulEnvironment.js` として以下のJSファイルを作成する。

```javascript:getContentfulEnvironment.js
require('dotenv').config();

const contentfulManagement = require('contentful-management');

module.exports = function () {
  const contentfulClient = contentfulManagement.createClient({
    accessToken: process.env.CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN,
  });

  return contentfulClient
    .getSpace(process.env.CONTENTFUL_SPACE_ID)
    .then((space) => space.getEnvironment(process.env.CONTENTFUL_ENVIRONMENT));
};
```

保存したら、`npm run contentful-typescript-codegen` を実行する。成功すれば `@types/generated` 下に `contentful.d.ts` として型定義ファイルが生成されている。

# APIクライアントを定義する
自分はプロジェクトに `utils` ディレクトリを作り、そこに `client.ts` として定義した。

```typescript:client.ts
import { createClient } from 'contentful';

// contentful の APIクライアント
const client = createClient({
  accessToken: process.env.CONTENTFUL_DELIVERY_TOKEN || '',
  space: process.env.CONTENTFUL_SPACE_ID || '',
});

export default client;
```

上のAPIクライアントではいくつかの環境変数を参照している。Next.jsの場合、`.env.local` ファイルを作成し、以下のように用意しておけば良い。ここでも中身はContentfulのAPIページからtokenをコピペしておく。

```env:.env.local
CONTENTFUL_SPACE_ID = ****
CONTENTFUL_ENVIRONMENT = ****
CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN = ****
CONTENTFUL_DELIVERY_TOKEN = ****
CONTENTFUL_PREVIEW_TOKEN = ****
```

# Next.jsでSSGする
ここからの内容は自分がContentfulに用意したコンテツのフィールド名に依存している。ここではブログを作るという想定で、`Post` という `Content type` を定義したとして進める。なので、コンテンツタイプは `post` になっているし、TypeScriptの型は `Post` をベースとした名前で生成されている。

## 記事一覧の取得
SSGによってレンダリングする記事一覧ページのコンポーネントは以下のようになる。

```typescript:Home.tsx
interface Props {
  posts: EntryCollection<IPostFields>;
};

const Home: React.FC<Props> = ({ posts }) => (
  // 省略
)

export default Home;

// Next.js の SSG のためのコード
export const getStaticProps: GetStaticProps<Props> = async () => {
  const posts = await client
    .getEntries<IPostFields>({
      content_type: 'post',
    })
    .then((result) => {
      return result;
    });
  return {
    props: {
      posts,
    },
  };
};

```

一覧の取得はAPIクライアントで `getEntries()` というメソッドを利用する。引数にコンテンツタイプ（ここでは 'post'）を指定することで、目的の種類のコンテンツだけを取得することができる。

Contentfulが返すコンテンツは、自分が定義したコンテツが入る `fields` プロパティの他に、`sys` というプロパティで、投稿日やIDなどシステム側で設定された値を持っている。別コンテンツへリンクを作成する際にはこのIDを使用することになる。

エラーハンドリングができていないところがまだイマイチだけど、こんなイメージで使用できる。

## 1件の記事の取得
```typescript:Post.tsx
interface Props {
  post: Entry<IPostFields>;
}

const Post: React.FC<Props> = ({ post }) => (
  // 省略
)

export default Post;

interface Params extends ParsedUrlQuery {
  id: string;
}

export const getStaticPaths: GetStaticPaths = async () => {
  const posts = await client.getEntries<IPostFields>().then((result) => {
    return result;
  });
  const paths = posts.items.map((item) => `/blog/${item.sys.id}`);
  return { paths, fallback: false };
};

export const getStaticProps: GetStaticProps<Props, Params> = async (
  context
) => {
  const id = context.params?.id || '';
  const post = await client.getEntry<IPostFields>(id).then((result) => {
    return result;
  });
  return {
    props: {
      post,
    },
  };
};
```

ビルド時にページのパスを決定するための `getStaticPaths` と、Porpsを渡すための `getStaticProps` を定義している。こちらもエラーハンドリングができていなかったり、IDが `undefined` のときに空文字を充てているなど、まだまだイケてないところがある。

# さいごに
Contentfulは柔軟にコンテンツを構成できる一方で、APIから帰ってくるオブジェクトも複雑なネスト構造になりやすい。しかし、型があることでそんなネスト構造は知らなくとも、サジェストに従っていけば迷わず目的のコンテンツを参照することができる。コンテンツ構造を変えたときにも、型を自動生成すれば修正も楽である。JSONとにらめっこしながらオブジェクトに潜っていく必要はない。


Contentfulで型安全にコンテンツを取得する

# Hello World
ContentfulとNext.js、そしてVercelを使ってポートフォリオ兼技術ブログとなるサイトを作った。フロントエンドエンジニアとして、単に技術の知識を共有するだけでなく、フロントエンド技術を実験する場、そしてそれがそのままポートフォリオになるような場がほしいなと思って開設した。

実は最近ずっと[サーバーサイドも自分で実装しようと奮闘していた](https://github.com/yokotani92/my-app)んだけど、考えれば考えるほど実現に向けて避けられない課題が見えてきて、一旦そこは諦めることにした。TODOリストくらいならいいんだけど、まだはっきり仕様も固まっていないブログサービスのAPIを開発するとなると自分の力量的に難しかった。

ということで、このサイト、ブログ記事の管理にContentfulというHeadless CMSを利用することにした。要件がふわっとしている今の自分にとって、フロントエンドを自由に実装でき、柔軟にコンテンツの構造を変えられるHeadless CMSはこれ以上なくマッチしていた。日本製のmicroCMSなどもあったけど、サービスとしてのメジャー度と、コンテンツの自由度の高さ、TypeScriptとの相性の良さからこちらを選択した。（特にAPIの型を自動生成できるのはかなり嬉しかったのでそのうち記事にしたい。）ただ、microCMSも素晴らしいサービスで、個人的にUIはそちらのほうが好きだったし、Next.jsを使ったスターター的なドキュメントが用意されていたのも好印象だった。

バックエンドの自力実装を諦めHeadless CMSを使うと決めてからはデプロイまで順調だった。だだバックエンドの実装も諦めたわけではなくて、むしろ絶対にやりとげなければという決意を新たにしたところなので、今後はその試行錯誤を記事にしていきたいと思っている。そういう意味でもひとつここに場所ができて良かった。

P.S. 下はMarkdownをマークアップしているサンプル。このサイトではマークアップに [`marked`](https://www.npmjs.com/package/marked) 、Syntax Highlightには [`highlight.js`](https://www.npmjs.com/package/highlight.js?activeTab=readme) というライブラリを使っている。

---

# これは見出しh1です
これは最初の本文です。これは最初の本文です。これは最初の本文です。これは最初の本文です。これは最初の本文です。これは最初の本文です。これは最初の本文です。これは最初の本文です。これは最初の本文です。これは最初の本文です。これは最初の本文です。これは最初の本文です。これは最初の本文です。これは最初の本文です。これは最初の本文です。これは最初の本文です。これは最初の本文です。これは最初の本文です。

## これは見出しh2です
- 箇条書きテスト1
- 箇条書きテスト2
- 箇条書きテスト3

### これは見出しh3です
> これは引用文です。

> error:重要な警告
> 
> これは重要な警告です。

> warn:軽度な警告
> 
> これは軽度な警告です。

> info:お役立ち情報
> 
> これはお役立ち情報です。

> success:チェック項目
> 
> これはチェック項目です。

#### これは見出しh4です
```typescript:syntaxHighlightTest.ts
class MyClass {
  public static myValue: string;
  constructor(init: string) {
    this.myValue = init;
  }
}
import fs = require("fs");
module MyModule {
  export interface MyInterface extends Other {
    myProperty: any;
  }
}
declare magicNumber number;
myArray.forEach(() => { }); // fat arrow syntax
```

インラインコードのテスト `test` です。

インライン数式のテスト `$c = \pm\sqrt{a^2 + b^2}$` です。

数式のテストです。
```
$$c = \pm\sqrt{a^2 + b^2}$$
```

**最後に強調のテストをして、本文終わりです。**

Articles

Next.js, Contentful, markedの環境における数式表示

OGPを使ってMarkdownのリンクをカード型のリンクにマークアップする

Contentfulで型安全にコンテンツを取得する

ContentfulとNext.jsで作る技術ブログ