
在著手開發以前，我基於手裡擁有的先備條件做了幾項架構性的決定。

# 使用 Design System 管理佈景主題

任職於前公司時，我曾開發過一套 Design System，名為 `Essence`，雖然它不是百分之百完美的實作，但是視覺上是中文友善的獨立的系統，不會有像是 Bootstrap 等拉丁語系框架套在方塊字上面的違和感，再從可用性來說，Essence 已經使用在兩款產品上，算是經得起考驗；對於整個系統的作者我來說，開發介面肯定也是最熟悉不過了。因此無論從視覺角度、串接成本角度、開發時程角度來說，在我的部落格套用 Essence 無疑是最好的選擇。

# 使用 Multi-Workspace Monorepo 管理程式碼

身為一個獨立開發者，我不需要與其他人協作，因此 Source Code 的管理上採用 Monorepo 的策略，可以藉此降低我的管理成本。由於我使用的技術棧是 JavaScript 生態圈，因此通常會搭配 Multi-workspace 來區隔不同子專案的職責，但又能達到共享程式碼的好處。如果考慮到未來我不止有部落格專案，可能會有各式各樣想要嘗試的題目，那麼 Multi-workspace 也可以讓我降低新建專案的成本。

我的檔案架構如下：

```
project_root/
  - README.md
  - package.json
  - packages/
    - utils/ <------------ 所有專案共享的模組
      - package.json
      - ...
    - essence/ <---------- 佈景主題
      - package.json
      - ...
    - personal-blog/ <---- 部落格專案
      - package.json
      - ...
    - future-project/ <--- 未來的新專案
      - package.json
      - ...
```

# React.js & Next.js

技術棧的挑選純粹是基於個人熟悉程度以及市場主流工具，因此使用 React.js 搭配 Next.js 框架。

# 靜態網站生成 (SSG, Static Site Generation)

我的每一篇文章都是一個 `MDX` 檔案，並且儲存於 Source Code 的檔案裡，這代表我不需要依賴外部的資料庫，不需要動態產生網站頁面，只需要在建置階段產生所有網站內容就能部署了。這麼做帶來了幾個好處：

- 省去伺服器成本
- 只需要 Host 靜態檔案，因此有很多免費 Hosting 服務可以選擇
- 網站內容已經預產好，因此載入速度可以很快，也支援 SEO
- 如果 Online Build 的免費額度耗盡了，可以切換成 Offline Build

基礎建設

使用 Multi-Workspace Monorepo 管理程式碼

靜態網站生成 (SSG, Static Site Generation)


# Vercel vs. Netlify

既然我們使用了 Next.js 作為主要開發框架，那麼主流的 Hosting 通常就是 Vercel 或是 Netlify 了，差別在於 Vercel 的免費方案是反對商業使用的，如果需要在站內刊登廣告或是販售商品，建議可以使用 Netlify。

# 將部落格部署到 Vercel

如果讀者像我一樣打算把 Monorepo 部署到 Vercel，那麼我們必須進行一些客製化的設定：

1. 設定 Local 專案

    首先準備 Build 指令：

    ```json title="personal-blog/package.json"
    {
      // ...
      "scripts": {
        // ...
        "vercel": "next build && next export"
      },
      // ...
    }
    ```

    由於我們使用 SSG 生成 html 網站內容，為了避免路徑參雜副檔名，可以建立 vercel 的設定檔如下：

    ```json title="personal-blog/vercel.json"
    {
      "cleanUrls": true
    }
    ```

2. 設定 Vercel 專案

    | 欄位路徑 | 內容 |
    | -- | -- |
    | `General`.`Root Directory` | `packages/personal-blog` |
    | `Build & Development Settings`.`Build Command` | 覆寫為 `yarn vercel` |
    | `Build & Development Settings`.`Output Directory` | 覆寫為 `out` |

    ## 避免非必要的部署 [^1] [^2]

    [^1]: [How do I use the "Ignored Build Step" field on Vercel?](https://vercel.com/guides/how-do-i-use-the-ignored-build-step-field-on-vercel)
    [^2]: [How to prevent unnecessary Vercel builds](https://www.raulmelo.dev/til/how-to-prevent-unnecessary-vercel-builds)

    如果你的 Monorepo 有超過一個可部署的專案，那麼就必須避免 A 專案的改動觸發 B 專案的部署。解決方式之一是偵測特定 package 內的檔案變動，如果有變動則進行部署，若無變動則忽略部署。

    進入到專案設定 -> 點選 `Git` -> 捲動至 `Ignored Build Step` 欄位，輸入：

    ```
    git diff --quiet HEAD^ HEAD .
    ```

    此處需要特別注意，偵測的路徑是 `.` 而不是 `./packages/personal-blog`，因為我們在第一步的設定中已經調整過根目錄了，所以此處的路徑是相對於根目錄而言。

# 將部落格部署到 Netlify

1. 設定 Local 專案

    除了準備 Build 指令以外，由於 Netlify 預設使用 npm，因此可以使用 `packageManager` 指定使用 yarn：

    ```json title="personal-blog/package.json"
    {
      // ...
      "packageManager": "yarn@1.22.19",
      "scripts": {
        // ...
        "netlify": "next build && next export"
      },
      // ...
    }
    ```

2. 設定 Netlify 專案

    | 欄位 | 內容 |
    | -- | -- |
    | Base directory | `./packages/personal-blog` |
    | Build command | `yarn netlify` |
    | Publish directory | `./packages/personal-blog/out` |

    Netlify 預設就會偵測 base directory 內的檔案變動來決定是否要執行部署[^3]，因此不用像 Vercel 一樣手動設定來避免非必要的部署。

    [^3]: [Ignore builds](https://docs.netlify.com/configure-builds/ignore-builds/)

部署


# MDX 語法

身為一位開發者，肯定對於 Markdown 不陌生，身為 React 的開發者，肯定也對 Component 不陌生，而 MDX 語法正是 Markdown 與 Component 兩者的結合，它允許我們在 Markdown 語法裡穿插 JSX 語法，這使得 Markdown 速記語法如虎添翼，讓文章可以變得更為豐富多彩，簡單、易用、高度彈性等眾多好處讓我毫無懸念地採用 MDX 作為撰寫文章的主要語法，例如我可以這樣子寫文章：

```md
# Work Experience

<Inline justifyContent="space-between" alignItems="center" gap="s" wrap="wrap">
## Senior Backend Engineer, [ĒSEN Inc.](https://www.linkedin.com/company/eseninc/)
*2022.03 - 2023.01*
</Inline>

- Kicked off both business-facing and customer-facing projects with microservice architecture and domaindriven design (DDD) pattern
- Implemented a reservation system with optimistic lock strategy to prevent double booking
- Implemented the design system Essence to modularize and accelerate frontend development
```

# Frontmatter 語法

慣例上使用 Markdown 撰寫部落格文章時都會搭配 `Frontmatter` 語法來補足細節設定，像是文章標題、摘要、發佈日期等，不是文章主體，卻又與文章相關的次要資訊。因此本站使用 MDX 時也應該支援 Frontmatter 語法，一般都是在檔案開頭使用 `---` 這個 fenced block 夾住 yaml 語法，然後才是 MDX 語法的內文，例如：

```md
---
title: 文章標題
publishDate: '2023-03-02'
keywords:
  - 關鍵字1
  - 關鍵字2
---

# Title

paragraph.
```

# 網站頁面 vs. 部落格文章

一個部落格除了文章以外，其實還會有站內的頁面，像是`關於網站`、`關於作者`、`作品集`等，他們也屬於作者所撰寫的內容，因此我希望這些網站頁面與部落格文章在撰寫時的體驗是一致的，都應該使用 MDX 語法來完成，差別在於網站頁面應遵守 Next.js 的檔案結構，而部落格文章則可以儲存於 Source Code 之外，所以我的檔案編排會是如以下所示結構：

```
personal-blog/
  - content/ <--- 部落格文章可以放在 pages 資料夾外
    - posts/
      - post1.mdx
      - post2.mdx
      - post3.mdx
      - ...
  - pages/ <--- 網站頁面遵循 Next.js 的路由規則
    - index.mdx
    - about-site.mdx
    - about-author.mdx
    - 404.js
    - ...
  - ...
```

# 渲染網站頁面

在 Next.js 官方文件 [Using MDX with Next.js](https://nextjs.org/docs/advanced-features/using-mdx) 當中已經有詳盡說明如何在你的專案使用 MDX，基本上照著操作就能順利渲染 `pages/*.mdx` 了，以下是我的設定方式：

1. 安裝相依

    ```shell
    yarn workspace @app/personal-blog add \
      @mdx-js/loader \
      @mdx-js/react \
      @next/mdx \
      remark-frontmatter \
      remark-gfm
    ```

2. 設定 `next.config`

    ```js title="personal-blog/next.config.mjs"
    import createMDXDecorator from '@next/mdx'
    import { getMdxOptions } from './utils/mdx.mjs'

    const withMDX = createMDXDecorator({
      extension: /\.mdx?$/,
      options: {
        ...getMdxOptions(),
        // If you use `MDXProvider`, uncomment the following line.
        providerImportSource: '@mdx-js/react',
      },
    })

    const nextConfig = {
      transpilePackages: ['@module/utils', '@module/essence'],
      reactStrictMode: true,
      pageExtensions: ['js', 'jsx', 'md', 'mdx'],
      // ...
    }

    export default withMDX(nextConfig)
    ```

    此處把 MDX 外掛的設定獨立出來，方便管理及重用：

    ```js title="personal-blog/utils/mdx.mjs"
    import remarkFrontmatter from 'remark-frontmatter'
    import remarkGfm from 'remark-gfm'

    export const getMdxOptions = () => {
      return {
        remarkPlugins: [
          remarkFrontmatter,
          remarkGfm,
        ],
        rehypePlugins: [],
      }
    }
    ```

3. 使用客製化元件

    如果想要客製化渲染 MDX 內容時使用的 Component，首先要準備一個客製元件對照表：

    ```js title="personal-blog/components/mdx/MDXComponents.js"
    import Text from '@module/essence/components/Text' // 使用來自 Design System 的元件

    const MDXComponents = {
      p: (props) => <Text {...props} />,
    }

    export default MDXComponents
    ```

    接下來可以在應用程式的最外層注入這些客製化元件：

    ```jsx title="personal-blog/pages/_app.js"
    import { MDXProvider } from '@mdx-js/react'
    import MDXComponents from '../components/mdx/MDXComponents'

    const MyApp = ({ Component, pageProps }) => {
      return (
        <MDXProvider components={MDXComponents}>
          <Component {...pageProps} />
        </MDXProvider>
      )
    }

    export default MyApp
    ```

    如果你的部落格可能需要支援多種風格的客製化元件，也可以考慮把 `MDXProvider` 放在 Layout Component：

    ```js title="personal-blog/components/layout/SitePageLayout.js"
    import { MDXProvider } from '@mdx-js/react'
    import Container from '@module/essence/components/Container'
    import MDXComponents from '../mdx/MDXComponents'

    export default ({ children, ...rest }) => {
      return (
        <Container fluid {...rest}>
          <MDXProvider components={MDXComponents}>{children}</MDXProvider>
        </Container>
      )
    }
    ```

    但是要記得在 MDX 頁面使用 `export` 來指定 Layout：

    ```md title="personal-blog/pages/example.mdx"
    import SitePageLayout from '../components/layout/SitePageLayout'
    export default ({ children }) => <SitePageLayout>{children}</SitePageLayout>

    # 標題一

    內文。
    ```

# 渲染部落格文章

接下來讓我們來看看如何渲染 Source Code 以外的 MDX 檔案。

1. 路由

    假設我們希望每篇文章的網址形式長成像是 `https://example.com/blog/some-awesome-slug` 這樣，那麼按照 Next.js 的標準使用方式，我們可以建立頁面 `pages/blog/[postSlug]/index.js` 來處理動態的 `postSlug`：

    ```jsx title="personal-blog/pages/blog/[postSlug]/index.js" highlightLines="11-15"
    import { getPosts } from '../../../utils/post' // 下文將會解釋

    const BlogPostPage = () => {
      // ...
      return 
    }

    export async function getStaticPaths() {
      const posts = getPosts()
      return {
        paths: posts.map(post => ({
          params: {
            postSlug: post.slug,
          },
        })),
        fallback: false, // can also be true or 'blocking'
      }
    }
    
    export default BlogPostPage
    ```

2. 渲染 MDX 內容

    這裡我使用了 `next-mdx-remote` 這個 Library 來輔助我把 MDX 文字渲染成 React 元件，所以首先安裝這個相依：

    ```shell
    yarn workspace @app/personal-blog add next-mdx-remote
    ```

    接著修改 `pages/blog/[postSlug]/index.js`，將 MDX 原始碼 `serialize` 之後傳遞給 `<MDXRemote />` 即可渲染出內容了：

    ```jsx title="personal-blog/pages/blog/[postSlug]/index.js" highlightLines="11,23-28"
    import Container from '@module/essence/components/Container'
    import { MDXRemote } from 'next-mdx-remote'
    import { serialize } from 'next-mdx-remote/serialize'
    import { getMdxOptions } from '../../../utils/mdx.mjs'
    import { getPostByPostSlug, getPosts } from '../../../utils/post' // 下文將會解釋

    const BlogPostPage = ({ post, mdxSource }) => {
      return (
        <Container fluid>
          <h1>{post.frontmatter.title}</h1>
          <MDXRemote {...mdxSource} components={MDXComponents} />
        </Container>
      )
    }

    export async function getStaticPaths() {
      // ...
    }

    export const getStaticProps = async ({ params }) => {
      const { postSlug } = params
      const post = getPostByPostSlug(postSlug)
      const mdxSource = await serialize(post.content, {
        mdxOptions: {
          ...getMdxOptions(),
          format: 'mdx',
        },
      })
      return {
        props: {
          post,
          mdxSource,
        },
      }
    }

    export default BlogPostPage
    ```

3. 使用 `fs` 讀取 MDX 原始內容

    在上方的程式碼中，我們使用到了兩個 utility functions `getPosts` 與 `getPostByPostSlug`，分別可以取得文章列表，以及根據 Slug 取得特定文章。這背後的實作其實只有單純地操作檔案系統，也因此我們的部落格文章儲存位置不必受限於 Next.js 的規範。
    
    處理 MDX 內容時會需要同時解析 Frontmatter，可以使用 `gray-matter` 這個 Library：

    ```shell
    yarn workspace @app/personal-blog add gray-matter
    ```

    我的 utility function 實作約略如下：

    ```js title="personal-blog/utils/post.js"
    import fs from 'fs'
    import matter from 'gray-matter'
    import path from 'path'

    class BlogPost {
      constructor(absoluteMDXFilePath) {
        this.absoluteFilePath = absoluteMDXFilePath
        this.parsedPath = path.parse(this.absoluteFilePath)
        this.fileContent = fs.readFileSync(this.absoluteFilePath, 'utf-8')
        const parsedFileContent = matter(this.fileContent)
        this.frontMatter = parsedFileContent.data
        this.slug =
          this.frontMatter.index?.partialSlug ||
          this.parsedPath.name.replace(/.mdx$/, '')
        this.content = parsedFileContent.content
      }

      toSerializable() {
        let serialized = {
          slug: this.slug,
          frontMatter: this.frontMatter,
          content: this.content,
        }
        return serialized
      }
    }

    export const getPosts = () => {
      const files = fs.readdirSync(path.join(process.cwd(), 'content/posts'), {
        withFileTypes: true,
      })
      const posts = files.map((file) => {
        let blogPost
        if (file.isDirectory()) {
          blogPost = new BlogPost(
            path.join(process.cwd(), 'content/posts', file.name, 'index.mdx')
          )
        } else {
          blogPost = new BlogPost(
            path.join(process.cwd(), 'content/posts', file.name)
          )
        }
        return blogPost.toSerializable()
      })
      return posts
    }

    export const getPostByPostSlug = (postSlug) => {
      const posts = getPosts()
      const post = posts.find((post) => post.slug === postSlug)
      return post
    }
    ```

    使用上需要特別注意，我們可能會使用 `getStaticProps` 來傳遞 post 的 instance 給 React Component，但是只有相容 JSON 的資料格式可以被傳遞，因此 `BlogPost` 提供了 `toSerializable()` 這個方法來處理 instance 的序列化。

文章內容管理


# 渲染文章索引列表

從前面的文章中，我們已經知道如何渲染一篇文章，接下來只要如法泡製，就能建立一個索引頁面列出部落格中所有的文章了。

```jsx title="personal-blog/pages/blog/index.js"
import Container from '@module/essence/components/Container'
import Heading from '@module/essence/components/Heading'
import { getPosts } from '../../utils/post'

const BlogPostIndexPage = ({ posts }) => {
  return (
    <Container>
      {posts.map((post) => (
        <Link key={post.slug} fluid href={`/blog/${post.slug}`}>
          <Heading size="m">{post.frontMatter.title}</Heading>
        </Link>
      ))}
    </Container>
  )
}

export const getStaticProps = ({ params }) => {
  return {
    props: {
      posts: getPosts()
    },
  }
}

export default BlogPostIndexPage
```

# 分頁處理

當文章數量不多時，或許唯一的索引頁面是一個可行的做法，但隨著部落格的經營，文章只會增加不會減少，如果文章數量達到某個規模時，勢必要採取某些方法讓這個索引頁面不要過度膨脹。目前這個階段，我傾向使用分頁來管理，因為對於讀者來說，仍然有辦法透過前往不同的分頁來瀏覽完所有文章。如果文章再成長到下一個規模時，或許就要捨棄分頁，改用關鍵字搜尋了，但分頁機制對於目前的部落格規模來說已經十分足夠！

我的實作方式是建立每一個分頁的路由頁面，並且擴充 utility functions 以支援分頁計算。

1. 路由

    ```jsx title="personal-blog/pages/blog/page/[pageId].js"
    import Container from '@module/essence/components/Container'
    import Heading from '@module/essence/components/Heading'
    import Label from '@module/essence/components/Label'
    import { getPosts, getPostsByPageSizeAndPageId } from '../../../utils/post'

    const BlogPostIndexPage = ({ posts, pagination }) => {
      return (
        <Container>
          {posts.map((post) => (
            <Link key={post.slug} fluid href={`/blog/${post.slug}`}>
              <Heading size="m">{post.frontMatter.title}</Heading>
            </Link>
          ))}
          <Label size="m">
            第{pagination.pageId}頁，共{pagination.pageCount}頁
          </Label>
        </Container>
      )
    }

    export async function getStaticPaths() {
      const BLOG_PAGE_SIZE = 10
      const posts = await getPosts()
      const pageCount = Math.ceil(posts.length / BLOG_PAGE_SIZE)
      return {
        paths: Array(pageCount)
          .fill(0)
          .map((_, pageIndex) => {
            const pageId = `${pageIndex + 1}`
            return {
              params: {
                pageId,
              },
            }
          }),
        fallback: false, // can also be true or 'blocking'
      }
    }

    export const getStaticProps = ({ params }) => {
      const BLOG_PAGE_SIZE = 10
      const posts = getPosts()
      const pageCount = Math.ceil(posts.length / BLOG_PAGE_SIZE)
      const { pageId } = params
      const currentPagedPosts = getPostsByPageSizeAndPageId(BLOG_PAGE_SIZE, pageId)
      return {
        props: {
          posts: currentPagedPosts,
          pagination: {
            pageSize: BLOG_PAGE_SIZE,
            pageCount,
            pageId,
          },
        },
      }
    }

    export default BlogPostIndexPage
    ```

2. 分頁計算 utility functions

    只要能夠知道所有文章的數量，以及每頁文章數量，就能進行分頁計算，或是拿到屬於特定頁面的文章列表，此外，我還打算使用文章發佈日期進行排序。因此我們可以在 utility functions 實作 `getSortedPosts` 與 `getPostsByPageSizeAndPageId` 兩個函數：

    ```js title="personal-blog/utils/post.js"
    export const getPosts = () => {
      // ...
    }

    export const getSortedPosts = () => {
      const posts = getPosts()
      const sortedPosts = posts.sort((a, b) => {
        if (a.frontMatter.publishDate < b.frontMatter.publishDate) {
          return 1
        } else if (a.frontMatter.publishDate > b.frontMatter.publishDate) {
          return -1
        } else {
          return 0
        }
      })
      return sortedPosts
    }

    export const getPostsByPageSizeAndPageId = (pageSize, pageId) => {
      const sortedPosts = getSortedPosts()
      const offset = pageSize * (parseInt(pageId) - 1)
      return sortedPosts.slice(offset, offset + pageSize)
    }
    ```

如此一來，我們基本上已經滿足一個部落格所需要的最低功能了：
- 編輯者可以撰寫 MDX 文章檔案
- 讀者可以瀏覽具有分頁的文章列表
- 讀者可以點選特定文章並且瀏覽全文

相信讀者們也已具備足夠的知識，可以開始動手客製出自己的部落格，展開屬於自己的旅程了！關於功能性的講解在此先告一段落，後續文章將會開始介紹偏向營運層面以及閱讀體驗的功能，歡迎有興趣繼續鑽研的朋友一起看下去。

文章索引及分頁


# Sitemap

Sitemap 是提供搜尋引擎讀取站內頁面清單的常見方式，可以加速搜尋引擎幫我們的網站建立索引，而網站主需要做的事情就是在根目錄提供 `sitemap.xml` 檔案，檔案內容也需遵循 Sitemap 規範。

在 Next.js 的專案中，我們可以手動建立 `/public/sitemap.xml`、手動填入 xml，並以靜態檔案的方式部署。然而，每當我們的部落格新增或刪除文章時，就必須要手動更新 `sitemap.xml`，這顯然會造成管理上的困擾。為了解決這個問題，我的做法是取巧地建立一個空白頁面，但是在 `getStaticProps()` 裡渲染並輸出 `sitemap.xml`：

```js title="personal-blog/pages/generateSitemap.js"
import { writeToPublic } from '../utils/output'
import { getPosts } from '../utils/post'
import { generateSiteMapInXML } from '../utils/seo'

export default () => {}

export const getStaticProps = async () => {
  const posts = getPosts()
  const sitemap = generateSiteMapInXML(posts)
  writeToPublic('sitemap.xml', sitemap)
  return {
    props: {},
  }
}
```

此處獨立出 Utility function `writeToPublic`，負責把檔案寫入 `/public` 資料夾：

```js title="personal-blog/utils/output.js"
import fs from 'fs'
import path from 'path'

export const writeToPublic = (relativeFilePath, fileContent) => {
  const absoluteFilePath = path.join(process.cwd(), 'public', relativeFilePath)
  fs.writeFileSync(absoluteFilePath, fileContent)
}
```

Sitemap 檔案內容的渲染過程也獨立於 utility function `generateSiteMapInXML`：

```js title="personal-blog/utils/seo.js"
export const generateSiteMapInXML = (posts) => {
  return `<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
    ${posts
      .map(
        (post) => `
  <url>
    <loc>{`https://example.com/blog/${post.slug}`}</loc>
    <lastmod>${post.lastModifiedTime}</lastmod>
  </url>`
      )
      .join('')}
</urlset>`
}
```

最後記得把這一份建置檔案列入 gitignore：

```txt title="personal-blog/.gitignore"
/public/sitemap.xml
```

# 伺服器端渲染 (SSR, Server Side Rendering)

要讓搜尋引擎能夠理解我們的網站內容，除了使用 Sitemap 編列頁面索引以外，每一個獨立頁面也都要能夠支援伺服器端渲染（SSR），這樣子爬蟲程式讀取頁面時才能夠拿到結構化的 Html 及頁面內容，而不是拿到需要被 Evaluate 的 Javascript。不過，Next.js 原生就已經支援 SSR 了，我們不必做任何處理就能享有 SSR 的效果，SSG 的過程也可以直接使用 SSR 產生的內容。

雖然對於爬蟲程式而言我們不用做任何努力，但是部落格的佈景主題、客製化元件等都是延遲載入 CSS，對於真人閱讀者而言，將會先看到 SSR 產生的 HTML，等到 CSS 被載入之後才套用設計過的佈景主題，這段載入 CSS 的時間差會造成閱讀者看到頁面閃爍、抖動、跳躍而影響閱讀體驗，為了讀者的眼睛著想，我的解法是把 CSS 納入 SSR 的過程當中。

由於我的 Design System 和各種調整樣式的處理方式都是透過 `styled-components` 來完成，所以只要替 styled-components 設定 SSR 即可，參考 [How to Set up Styled-Components with SSR in NextJS (Typescript)](https://reacthustle.com/blog/nextjs-styled-components-ssr-typescript) 一文之後，兩個步驟就能搞定：

1. 調整 Next Config

    ```js title="personal-blog/next.config.mjs" highlightLines="3-5"
    const nextConfig = {
      // ...
      compiler: {
        styledComponents: true,
      },
    }

    export default withMDX(nextConfig)
    ```

2. 更新 `_document.js`

    ```jsx title="personal-blog/pages/_document.js"
    import Document, { Head, Html, Main, NextScript } from 'next/document'
    import { ServerStyleSheet } from 'styled-components'

    class MyDocument extends Document {
      static async getInitialProps(ctx) {
        const sheet = new ServerStyleSheet()
        const originalRenderPage = ctx.renderPage
        try {
          ctx.renderPage = () =>
            originalRenderPage({
              enhanceApp: (App) => (props) =>
                sheet.collectStyles(<App {...props} />), //gets the styles from all the components inside <App>
            })
          const initialProps = await Document.getInitialProps(ctx)
          return {
            ...initialProps,
            styles: (
              <>
                {initialProps.styles}
                {sheet.getStyleElement()}
              </>
            ),
          }
        } finally {
          sheet.seal()
        }
      }

      render() {
        return (
          <Html>
            <Head />
            <body>
              <Main />
              <NextScript />
            </body>
          </Html>
        )
      }
    }

    export default MyDocument
    ```

# JSON-LD

JSON-LD 是一種結構化語法，用來描述網站的型態及內容，搜尋引擎也會針對帶有 JSON-LD 的網頁呈現特化的搜尋結果排版。使用方式其實就是在網頁裡插入 `<script />` 標籤，而內容只要依照 [Schema.org](https://schema.org/) 的規範填寫即可。

我的實作是撰寫專用的 SEO 元件，並且在文章頁面插入該元件：

```jsx title="personal-blog/components/utility/SEO.js"
import Head from 'next/head'
import { generateJsonLdForPost } from '../../utils/seo'

export default ({ post }) => {
  return (
    <Head>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{
          __html: generateJsonLdForPost(post),
        }}
        key="product-jsonld"
      />
    </Head>
  )
}
```

並且搭配 utility function 來產生 JSON-LD 內容：

```js title="personal-blog/utils/seo.js"
export const generateJsonLdForPost = (post) => {
  const { HOST, SITE_NAME, AUTHOR_NAME } = getConfig()
  const jsonLd = {
    '@context': 'https://schema.org',
    '@type': 'BlogPosting',
    headline: post.frontMatter.title,
    genre: ['SEO', 'JSON-LD'],
    keywords: post.frontMatter?.keywords || [],
    url: getUrl(HOST, post),
    datePublished: post.frontMatter.publishDate,
    dateCreated: post.frontMatter.publishDate,
    dateModified: post.lastModifiedTime,
    articleBody: post.content,
    publisher: {
      '@type': 'Organization',
      name: SITE_NAME,
      url: HOST,
      logo: {
        '@type': 'ImageObject',
        url: `${HOST}/site/favicon.svg`,
      },
    },
    author: {
      '@type': 'Person',
      name: AUTHOR_NAME,
      url: HOST,
    },
    creator: {
      '@type': 'Person',
      name: AUTHOR_NAME,
    },
    mainEntityOfPage: {
      '@type': 'WebPage',
      '@id': `${HOST}/blog`,
    },
  }
  if (post.frontMatter.hero) {
    jsonLd.image = `${HOST}${post.frontMatter.hero.src}`
  }
  if (post.frontMatter.excerpt) {
    jsonLd.description = post.frontMatter.excerpt
  }
  return JSON.stringify(jsonLd)
}
```

## 測試 JSON-LD

如果想要驗證自己的 JSON-LD 是否正確，可以參閱 Google 的文件「[測試結構化資料](https://developers.google.com/search/docs/appearance/structured-data)」。

SEO 搜尋引擎最佳化

伺服器端渲染 (SSR, Server Side Rendering)


多年以來，我一直想要有一個既能專注於寫作，又能高度客製化文章視覺的部落格系統，過去雖嘗試過 Blogger, Wordpress, Self-hosting, Hexo, Gatsby, Medium, Vocus 等方法，但每個平台終究會遇到難以應付的不便利之處，服務倒閉、文章搬遷困難、不支援 Markdown 語法、免費額度限制、被分潤機制強迫吸血，以上種種困難使我長久無法找到心目中理想的方案。

幸運的是，近年來前端生態蓬勃發展，React.js 及 Next.js 的誕生與演進讓自建部落格的門檻大幅下降，加上工作上的經驗累積，我已有足夠的能力從頭開發屬於自己的部落格，開發過程中關鍵的決策、思路、實作細節都將收錄在本系列文章當中。

欄位路徑	內容
General.Root Directory	packages/personal-blog
Build & Development Settings.Build Command	覆寫為 yarn vercel
Build & Development Settings.Output Directory	覆寫為 out

部署

Vercel vs. Netlify
#

#

將部落格部署到 Vercel
#

#

避免非必要的部署 ¹ ²
#

#

將部落格部署到 Netlify
#

#

目錄

欄位	內容
Base directory	./packages/personal-blog
Build command	yarn netlify
Publish directory	./packages/personal-blog/out

部署

Vercel vs. Netlify#

#

將部落格部署到 Vercel#

#

避免非必要的部署 1 2#

#

將部落格部署到 Netlify#

#

註釋#

#

目錄

Vercel vs. Netlify
#

將部落格部署到 Vercel
#

避免非必要的部署 ¹ ²
#

將部落格部署到 Netlify
#

註釋
#