From f77aa484c8c43a5e0f3435a894d30c1adeda0402 Mon Sep 17 00:00:00 2001 From: brklntmhwk_dev <86272619+brklntmhwk@users.noreply.github.com> Date: Tue, 26 Nov 2024 00:29:51 +0000 Subject: [PATCH 1/4] =?UTF-8?q?ci(dev):=20=F0=9F=8E=A1=20revert=20the=20ca?= =?UTF-8?q?che=20step?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/ci.yml | 8 ++++++++ .github/workflows/danger.yml | 8 ++++++++ .github/workflows/prod.yml | 16 ++++++++-------- 3 files changed, 24 insertions(+), 8 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a7aca7d5..355d94a0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -38,6 +38,14 @@ jobs: uses: actions/checkout@v4 - name: Set up Bun with Mise uses: jdx/mise-action@v2 + - name: Set up bun store and build artifact cache + uses: actions/cache@v4 + with: + path: | + ~/.bun/install/cache + key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lockb') }} + restore-keys: | + ${{ runner.os }}-bun- - name: Install dependencies run: bun i --no-save - name: Build project diff --git a/.github/workflows/danger.yml b/.github/workflows/danger.yml index d6cc023c..71cef922 100644 --- a/.github/workflows/danger.yml +++ b/.github/workflows/danger.yml @@ -18,6 +18,14 @@ jobs: uses: actions/checkout@v4 - name: Set up Bun with Mise uses: jdx/mise-action@v2 + - name: Set up bun store and build artifact cache + uses: actions/cache@v4 + with: + path: | + ~/.bun/install/cache + key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lockb') }} + restore-keys: | + ${{ runner.os }}-bun- - name: Install dependencies run: bun i --no-save - name: Danger diff --git a/.github/workflows/prod.yml b/.github/workflows/prod.yml index 67737f38..a8ae7eaa 100644 --- a/.github/workflows/prod.yml +++ b/.github/workflows/prod.yml @@ -19,14 +19,14 @@ jobs: uses: actions/checkout@v4 - name: Set up Bun with Mise uses: jdx/mise-action@v2 - # - name: Set up bun store and build artifact cache - # uses: actions/cache@v4 - # with: - # path: | - # ~/.bun/install/cache - # key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lockb') }} - # restore-keys: | - # ${{ runner.os }}-bun- + - name: Set up bun store and build artifact cache + uses: actions/cache@v4 + with: + path: | + ~/.bun/install/cache + key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lockb') }} + restore-keys: | + ${{ runner.os }}-bun- - name: Install dependencies run: bun i --no-save - name: Build project From 158c086e05f5254d45c542f08be1f8c8ee0f5627 Mon Sep 17 00:00:00 2001 From: brklntmhwk_dev <86272619+brklntmhwk@users.noreply.github.com> Date: Tue, 26 Nov 2024 01:23:31 +0000 Subject: [PATCH 2/4] =?UTF-8?q?style(ui):=20=F0=9F=92=84=20tweak=20styles?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit modify the grid layout of card-grid & add dark mode compatibility to the text color of th --- src/components/elements/Card/CardGrid.astro | 8 +++++--- tailwind.config.ts | 1 + 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/src/components/elements/Card/CardGrid.astro b/src/components/elements/Card/CardGrid.astro index 7a08be97..a85999ff 100644 --- a/src/components/elements/Card/CardGrid.astro +++ b/src/components/elements/Card/CardGrid.astro @@ -9,9 +9,11 @@ const props = Astro.props;
Date: Tue, 26 Nov 2024 01:26:50 +0000 Subject: [PATCH 3/4] =?UTF-8?q?docs(content):=20=F0=9F=93=96=20tweak=20exi?= =?UTF-8?q?sting=20articles?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/content/blog/en/astro-website.mdx | 4 ++-- src/content/page/en/tools.mdx | 4 ++-- src/content/page/ja/tools.mdx | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/content/blog/en/astro-website.mdx b/src/content/blog/en/astro-website.mdx index d118fe54..5dca17b7 100644 --- a/src/content/blog/en/astro-website.mdx +++ b/src/content/blog/en/astro-website.mdx @@ -2,7 +2,7 @@ title: Build a Personal Website with Astro, Cloudflare Pages, D1, and Front Matter CMS description: A dev story behind building my website for geeks wanting to have their own in the era of video. It's built using Astro, Cloudflare Pages, D1, Front Matter CMS, etc. publishedAt: 2024-07-13T00:34:54.000Z -modifiedAt: 2024-11-22T02:37:23.028Z +modifiedAt: 2024-11-26T01:24:09.003Z draft: published type: blog category: @@ -50,7 +50,7 @@ It's called a "metaframework" in that you can leverage other JS frameworks as yo For more details, see [the official homepage](https://docs.astro.build/en/getting-started/). -It's geared toward service like corpolate websites or blog where user interactions are unilateral rather than bilateral (e.g. EC, SNS) +It's geared toward service like corporate websites or blog where user interactions are unilateral rather than bilateral (e.g. EC, SNS) In my case, I mainly use what Astro offers and partly rely on [SolidJS](https://www.solidjs.com/). Also, almost all code is written in TypeScript and TSX. I couldn't have helped shaking like a leaf without them. diff --git a/src/content/page/en/tools.mdx b/src/content/page/en/tools.mdx index 22abb2c8..b0c73689 100644 --- a/src/content/page/en/tools.mdx +++ b/src/content/page/en/tools.mdx @@ -1,7 +1,7 @@ --- title: Tools I Use fmContentType: page -modifiedAt: 2024-11-25T07:29:58.500Z +modifiedAt: 2024-11-26T01:25:33.716Z description: Here are software & hardware tools I use daily. --- @@ -31,7 +31,7 @@ Bluetooth Earphones E-book Reader ::: :::card -[![ The Endpoint ](../../../assets/images/the-endpoint.jpg)](https://younagi.dev/split-keyboard-the-endpoint-build/) +[![ The Endpoint ](../../../assets/images/the-endpoint.jpg)](https://younagi.dev/blog/split-keyboard-the-endpoint-build/) **The Endpoint** A split keyboard ::: diff --git a/src/content/page/ja/tools.mdx b/src/content/page/ja/tools.mdx index 6f9dc692..c8f99a17 100644 --- a/src/content/page/ja/tools.mdx +++ b/src/content/page/ja/tools.mdx @@ -1,7 +1,7 @@ --- title: 愛用ツール群 fmContentType: page -modifiedAt: 2024-11-25T08:24:55.079Z +modifiedAt: 2024-11-26T01:25:46.029Z description: 私が普段使っているソフトウェア&ハードウェア群 --- @@ -31,7 +31,7 @@ Bluetooth 接続イヤホン 電子書籍リーダ ::: :::card -[![ The Endpoint ](../../../assets/images/the-endpoint.jpg)](https://younagi.dev/ja/split-keyboard-the-endpoint-build/) +[![ The Endpoint ](../../../assets/images/the-endpoint.jpg)](https://younagi.dev/ja/blog/split-keyboard-the-endpoint-build/) **The Endpoint** 左右分割型キーボード ::: From 94845e2de3d52c195c416af41f30ecb897fc176e Mon Sep 17 00:00:00 2001 From: brklntmhwk_dev <86272619+brklntmhwk@users.noreply.github.com> Date: Tue, 26 Nov 2024 08:47:09 +0000 Subject: [PATCH 4/4] =?UTF-8?q?docs(content):=20=F0=9F=93=96=20add=20new?= =?UTF-8?q?=20articles=20and=20tweak=20existing=20articles?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../en/astro-and-front-matter-cms-combi.mdx | 3 +- src/content/blog/en/astro-website.mdx | 13 +- .../blog/en/obsidian-knowledge-base.mdx | 5 +- src/content/blog/en/remark-card.mdx | 298 ++++++++++++++++++ .../total-newbie-builds-mini-itx-linux-pc.mdx | 3 +- .../ja/astro-and-front-matter-cms-combi.mdx | 3 +- src/content/blog/ja/astro-website.mdx | 3 +- .../blog/ja/obsidian-knowledge-base.mdx | 3 +- src/content/blog/ja/remark-card.mdx | 297 +++++++++++++++++ .../total-newbie-builds-mini-itx-linux-pc.mdx | 5 +- src/content/tags/en/tags.yml | 9 + src/content/tags/ja/tags.yml | 9 + 12 files changed, 636 insertions(+), 15 deletions(-) create mode 100644 src/content/blog/en/remark-card.mdx create mode 100644 src/content/blog/ja/remark-card.mdx diff --git a/src/content/blog/en/astro-and-front-matter-cms-combi.mdx b/src/content/blog/en/astro-and-front-matter-cms-combi.mdx index 4b2540e7..434b70c4 100644 --- a/src/content/blog/en/astro-and-front-matter-cms-combi.mdx +++ b/src/content/blog/en/astro-and-front-matter-cms-combi.mdx @@ -12,9 +12,10 @@ tags: - front-matter-cms - astro - vscode + - markdown level: 1 description: In the CMS community, a commet appeared all of a sudden as if putting an end to the chaos. It's Front Matter CMS. It might be the best match for websites built using Astro. -modifiedAt: 2024-11-21T06:42:35.096Z +modifiedAt: 2024-11-26T08:43:23.605Z --- ## Intro diff --git a/src/content/blog/en/astro-website.mdx b/src/content/blog/en/astro-website.mdx index 5dca17b7..6f75c8fc 100644 --- a/src/content/blog/en/astro-website.mdx +++ b/src/content/blog/en/astro-website.mdx @@ -1,10 +1,10 @@ --- -title: Build a Personal Website with Astro, Cloudflare Pages, D1, and Front Matter CMS -description: A dev story behind building my website for geeks wanting to have their own in the era of video. It's built using Astro, Cloudflare Pages, D1, Front Matter CMS, etc. -publishedAt: 2024-07-13T00:34:54.000Z -modifiedAt: 2024-11-26T01:24:09.003Z draft: published +level: 4 type: blog +title: Build a Personal Website using Astro, Cloudflare Pages, D1, and Front Matter CMS +publishedAt: 2024-07-13T00:34:54.000Z +modifiedAt: 2024-11-26T08:45:55.918Z category: metadata: en/categories slug: attempt @@ -15,7 +15,8 @@ tags: - typescript - front-matter-cms - cloudflare -level: 4 + - markdown +description: A dev story behind building my website for geeks wanting to have their own in the era of video. It's built using Astro, Cloudflare Pages, D1, Front Matter CMS, etc. --- ## Intro @@ -37,7 +38,7 @@ https://github.com/brklntmhwk/younagi.dev As of the day when I'm writing this article, my proficiency level in this field is as follows: - Have a three-year experience as a software engineer in total (Not in a row) -- Understand the basics of JavaScript, TypeScript, and Astro(For me) +- Understand the basics of JavaScript, TypeScript, and Astro(I hope so) - Have built several websites using Next.js or Astro ## Main diff --git a/src/content/blog/en/obsidian-knowledge-base.mdx b/src/content/blog/en/obsidian-knowledge-base.mdx index aebb0b1f..a9645053 100644 --- a/src/content/blog/en/obsidian-knowledge-base.mdx +++ b/src/content/blog/en/obsidian-knowledge-base.mdx @@ -5,7 +5,7 @@ type: blog title: Create an Obsidian starter kit for knowledge base "NPKB" publishedAt: 2024-09-05T04:11:06.403Z fmContentType: blog -modifiedAt: 2024-11-25T07:16:07.748Z +modifiedAt: 2024-11-26T08:44:04.376Z category: metadata: en/categories slug: attempt @@ -14,6 +14,7 @@ tags: slugList: - obsidian - javascript + - markdown description: I love Obsidian. It's fully custamizable but...tremendously laborisous to setup the environment from scratch. Here is mine that I continued updating for several years. image: /src/assets/images/npkb.png --- @@ -44,7 +45,7 @@ This article is written assuming readers understand the basics of [Git](https:// As of the day I'm writing this article, my proficiency level in this field is as follows: - Have a three-year experience as a software engineer in total (Not in a row) -- Understand the basics of JavaScript, CSS, and Markdown(for me) +- Understand the basics of JavaScript, CSS, and Markdown(I hope so) - Have been using Obsidian for 3 years ## Main diff --git a/src/content/blog/en/remark-card.mdx b/src/content/blog/en/remark-card.mdx new file mode 100644 index 00000000..f54cfac1 --- /dev/null +++ b/src/content/blog/en/remark-card.mdx @@ -0,0 +1,298 @@ +--- +draft: draft +level: 2 +type: blog +title: Create a Remark plugin "remark-card" and use it in my Astro website +publishedAt: 2024-11-26T01:30:34.391Z +fmContentType: blog +modifiedAt: 2024-11-26T08:42:33.557Z +category: + metadata: en/categories + slug: attempt +tags: + metadata: en/tags + slugList: + - typescript + - astro + - markdown +description: Cards always enthrall us just being there; we are hardwired to pay more attention to them than plain text. However, Markdown doesn't support it syntaxically. Why not create a plugin for it then? +--- + +## Intro + +Ever since childhood, I had dreamed of becoming a wizard—— + +The dream's come true this time. +But the ability is very limited; you cannot turn apples into apple pies, or someone you hate into Gudetama either. Instead, you can transform Markdown into whatever you want is HTML. + +By the way, [Unified](https://unifiedjs.com/), a huge ecosystem of document conversion as best represented by Remark and Rehype, has many volunteers scattered around the world who are developing and maintaining a lot of the plugins. +However, none of them says, "You can summon card components on the field in Markdown with me", as far as I can see. [^1] + +[^1]: There are a lot of plugins for "Linkcard" instead. + +Why not create it on your own then?—— Now that I feel like I can even fly. + +### Reader personas + +- Want to create a Remark plugin on their own +- Interested in `remark-card` +- Working hard on embellishing their Markdown/MDX blog + +### My proficiency level + +As of the day I'm writing this article, my proficiency level in this field is as follows: + +- Have a three-year experience as a software engineer in total (Not in a row) +- Understand the basics of JavaScript and TypeScript(I hope so) +- Have never published an NPM package before + +## Main + +Here's the Github repository. + +https://github.com/brklntmhwk/remark-card + +### How to use + +`remark-card` offers two Markdown dialects: `card-grid` and `card`. +The former plays a role as a wrapper for multiple cards and the latter is self-explanatory. + +> [!note] +> Hereafter, some HTML code in examples will be omitted for brevity if it's not relevant to the main theme here. (e.g., `class`) + +#### card + +The card is written in Markdown like: + +```markdown title="Markdown" +:::card +![younagi.dev](../../../assets/images/younagidev.jpg) +younagi.dev +::: +``` + +This turns into... + +```html title="HTML" +
+
+
+ + + + younagi.dev + +
younagi.dev
+
+
+
+ younagi.dev +
+
+``` + +And the final output is: + +:::card +![younagi.dev](../../../assets/images/younagidev.jpg) +younagi.dev +::: + +#### card-grid + +Next up, let's line up some cards in the card grid component. + +```markdown title="Markdown" +::::card-grid +:::card +![younagi.dev](../../../assets/images/younagidev.jpg) +younagi.dev Part 1 +::: +:::card +![younagi.dev](../../../assets/images/younagidev.jpg) +younagi.dev Part 2 +::: +:::card +![younagi.dev](../../../assets/images/younagidev.jpg) +younagi.dev Part 3 +::: +:::: +``` + +This turns into: + +```html title="HTML" +
+
+
+
+ + + + younagi.dev Part 1 + +
younagi.dev Part 1
+
+
+
+ younagi.dev Part 1 +
+
+
+
+
+ + + + younagi.dev Part 2 + +
younagi.dev Part 2
+
+
+
+ younagi.dev Part 2 +
+
+
+
+
+ + + + younagi.dev Part 3 + +
younagi.dev Part 3
+
+
+
+ younagi.dev Part 3 +
+
+
+``` + +And the final output is: + +::::card-grid +:::card +![younagi.dev](../../../assets/images/younagidev.jpg) +younagi.dev Part 1 +::: +:::card +![younagi.dev](../../../assets/images/younagidev.jpg) +younagi.dev Part 2 +::: +:::card +![younagi.dev](../../../assets/images/younagidev.jpg) +younagi.dev Part 3 +::: +:::: + +#### Use it in Astro + +Incidentally, the card components are already all over there in this website. + +https://younagi.dev/work/ + +To use Remark/Rehype plugins in Astro, you need to do something in the Astro config file at the root like this: + +```ts title="astro.config.ts" {2,10-19} +import { defineConfig /* ... */ } from "astro/config"; +import remarkCard, { type Config as RemarkCardConfig } from 'remark-card'; +// ... + +export default defineConfig({ + // ... + markdown: { + remarkPlugins: [ + // ... + [ + remarkCard, + { + customHTMLTags: { + enabled: true, + }, + cardGridClass: 'card-grid', + cardClass: 'card', + } satisfies RemarkCardConfig, + ], + // ... + ], + // ... + } + // ... +}); +``` + +This is actually enough to make it work, but it requires a bit more steps if you use Astro components to customize the HTML tags and styles. + +In my case, twe Astro components are used: `Card.astro` and `CardGrid.astro`. The resultant `card` and `card-grid` tags generated by `remark-card` will in turn be transformed into them respectively. +For more details, see the source code below. + +https://github.com/brklntmhwk/younagi.dev/tree/main/src/components/elements/Card + +Following [the MDX's manners](https://docs.astro.build/ja/guides/integrations-guide/mdx/#custom-components-with-imported-mdx), pass them onto the `` tag as custom components and the deal is all done. Below is an example of it: + +```ts title="~/lib/mdx-components.ts" +import { Card, CardGrid } from '@/components/elements/Card'; +// ... + +export const mdxComponents = { + // ... + card: Card, + 'card-grid': CardGrid, + // ... +}; +``` + +```astro title="~/pages/blog/[slug].astro" +--- +import BlogLayout from '@/layouts/BlogLayout.astro'; +import { mdxComponents } from '@/lib/mdx-components'; +import type { GetStaticPaths } from 'astro'; +// ... + +export const getStaticPaths = (async () => { + // ... +}) satisfies GetStaticPaths; + +const { entry } = Astro.props; +const { Content, headings } = await entry.render(); +--- + + + + +``` + +### Post-development notes + +It doesn't look different from README up until this point, so let me seriously think back on the dev experience here. + +- Language: ~~JavaScript~~ TypeScript + - I can't help shaking like a leaf without type safety + - ~~CommonJS~~ Following the ESM's manners +- Markdown syntax: [Generic directives/plugins syntax](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444) + - I made up such a dialect that anyone familiar with it will get taken aback at, and was going to adopt it at first, but ended up transitioning to the more general-looking syntax + - e.g., `:::`, `::::`, etc. +- Test runner & Package manager: [Bun](https://bun.sh/) + - It's a versatile meat bun being a JavaScript runtime, test runner, and package manager simultaneously + - Test-wise, it's compatible with [Jest](https://jestjs.io/ja/) and thus familiar to me and easy to migrate + - Its novelty and high performance were the determining factors + +I consumed the code written by forerunners as if bathing and it turned out to be written in the JavaScript and JSDoc combi in most cases. +It's agreeable if writing code for a product by and large [^2], but this time I went with TypeScript since it's such a small project. + +[^2]: Not writing in TypeScript saves you the time for transpiling while ensuring you type safety with JSDoc. +Plus, JSDoc helps you make decs in its manners, which make it easier to communicate with readers on the purposes of the code. + +## Outro + +Actually, I've developed and released another Remark plugin called `remark-video` soon after the `remark-card`. + +https://github.com/brklntmhwk/remark-video + +I was planning to make a new article about it at first, but gave up in the end. +After all, it didn't take me as much time and energy as the `remark-card` and therefore there's not enough thing to mention. On top of that, this article made me feel a tinge of contentment somehow. [^3] + +[^3]: Frankly speaking, I just found it tedious. diff --git a/src/content/blog/en/total-newbie-builds-mini-itx-linux-pc.mdx b/src/content/blog/en/total-newbie-builds-mini-itx-linux-pc.mdx index ffe7a753..22a22324 100644 --- a/src/content/blog/en/total-newbie-builds-mini-itx-linux-pc.mdx +++ b/src/content/blog/en/total-newbie-builds-mini-itx-linux-pc.mdx @@ -5,7 +5,7 @@ type: blog title: Total newbie builds Mini-ITX Linux PC (Error after Error) publishedAt: 2024-09-19T01:48:09.453Z fmContentType: blog -modifiedAt: 2024-11-25T08:21:58.432Z +modifiedAt: 2024-11-26T08:45:15.134Z category: metadata: en/categories slug: attempt @@ -15,6 +15,7 @@ tags: - error - pc - nixos + - linux description: A newbie recklessly builds Mini-ITX PC. From the beginner's view, some tricky points are explained through parts selection to OS installation. --- diff --git a/src/content/blog/ja/astro-and-front-matter-cms-combi.mdx b/src/content/blog/ja/astro-and-front-matter-cms-combi.mdx index 84697104..2defe846 100644 --- a/src/content/blog/ja/astro-and-front-matter-cms-combi.mdx +++ b/src/content/blog/ja/astro-and-front-matter-cms-combi.mdx @@ -12,9 +12,10 @@ tags: - front-matter-cms - astro - vscode + - markdown level: 1 description: 混沌とするCMS界隈に終止符を打つかのように突如として舞い降りた彗星「Front Matter CMS」Astro製ウェブサイトに最適かも？という話 -modifiedAt: 2024-11-21T06:38:17.256Z +modifiedAt: 2024-11-26T08:43:38.778Z --- ## 導入 diff --git a/src/content/blog/ja/astro-website.mdx b/src/content/blog/ja/astro-website.mdx index ba0f9229..2184dc7d 100644 --- a/src/content/blog/ja/astro-website.mdx +++ b/src/content/blog/ja/astro-website.mdx @@ -2,7 +2,7 @@ title: Astro + Cloudflare Pages + D1 + Front Matter CMS で個人ウェブサイトを作った description: 動画の時代に個人ブログという茨の道を歩みたいオタクなあなたに贈る開発体験記。Astro + Cloudflare Pages + D1 + Front Matter CMS とその他諸々の構成で作った個人ウェブサイトの諸機能を紹介 publishedAt: 2024-07-13T00:35:10.000Z -modifiedAt: 2024-11-25T07:04:32.396Z +modifiedAt: 2024-11-26T08:46:07.969Z draft: published type: blog category: @@ -15,6 +15,7 @@ tags: - typescript - front-matter-cms - cloudflare + - markdown level: 4 --- diff --git a/src/content/blog/ja/obsidian-knowledge-base.mdx b/src/content/blog/ja/obsidian-knowledge-base.mdx index 9b35f57a..35d48c23 100644 --- a/src/content/blog/ja/obsidian-knowledge-base.mdx +++ b/src/content/blog/ja/obsidian-knowledge-base.mdx @@ -5,7 +5,7 @@ type: blog title: Obsidian でナレッジベース用のスターターキット「NPKB」を作った publishedAt: 2024-09-05T04:10:55.070Z fmContentType: blog -modifiedAt: 2024-11-25T07:17:18.235Z +modifiedAt: 2024-11-26T08:44:12.888Z category: metadata: ja/categories slug: attempt @@ -14,6 +14,7 @@ tags: slugList: - obsidian - javascript + - markdown description: 「Obsidian ねぇ・・カスタマイズ性に優れててよいのだけど、一から環境を構築するのが大変なのよね」そこで数年改良を続け、私が普段愛用し続けている環境を本邦初公開する。 image: /src/assets/images/npkb.png --- diff --git a/src/content/blog/ja/remark-card.mdx b/src/content/blog/ja/remark-card.mdx new file mode 100644 index 00000000..1445c621 --- /dev/null +++ b/src/content/blog/ja/remark-card.mdx @@ -0,0 +1,297 @@ +--- +draft: draft +level: 2 +type: blog +title: Remark プラグイン「remark-card」を作って Astro 製ウェブサイトで使ってみた +publishedAt: 2024-11-26T01:30:34.391Z +fmContentType: blog +modifiedAt: 2024-11-26T08:42:45.816Z +category: + metadata: en/categories + slug: attempt +tags: + metadata: en/tags + slugList: + - typescript + - astro + - markdown +description: 古来、我々はカードの形をしたものに目がない。プレーンテキストと並んでいるとどうしてもカードの方に目を奪われてしまう。しかし、マークダウンでは構文的にサポート外である。それならプラグインで拡張すればいいじゃない？ +--- + +## 導入 + +{/* textlint-disable ja-technical-writing/ja-no-mixed-period */} +幼い頃から、魔法使いになることを夢見ていた—— + +この度、ようやくその念願が叶った。 +しかしその能力は限定的で、リンゴをアップルパイに変えたり、嫌いな人をマリモッコリに変えたりはできない。代わりに、マークダウンを望み通りの HTML に変えることならできる。 + +ところで、Remark や Rehype を擁する文書変換エコシステム「[Unified](https://unifiedjs.com/)」の下では、世界各地に点在する有志たちによって、数多のプラグインが日夜開発・メンテナンスされている。 +しかしザっと見渡す限り、「マークダウン記法でフィールド上にカードコンポーネントを召喚できる」と謳うものは存在しなかった。[^1] + +[^1]: カードはカードでも、リンクカードなら沢山ヒットしたのだが・・。 + +そういう訳で、無いなら自分で作ろうということに相成った。今なら、空だって飛べる気がする。 + +### 想定読者 + +- Remark プラグインを自分で作ってみたい +- `remark-card`に興味がある +- マークダウン/MDX のブログに彩りを添えようと躍起になっている + +### 現時点での私の習熟度 + +記事執筆時点での私の習熟度は次の通り。 + +- ソフトウェアエンジニアとして計 3 年の経験あり(勤続ではない) +- JavaScript、TypeScript の基本は理解している(つもり) +- NPM パッケージは公開したことがない + +## 本題 + +Github リポジトリはこちら。インストール方法については README に認めてあるので、ここでは触れない。 + +https://github.com/brklntmhwk/remark-card + +### 使い方 + +`remark-card`は`card-grid`、`card`の 2 つのマークダウン方言を提供する。 +前者はカードを複数表示する場合にラッパーの役割を果たし、後者はカード単体である。 + +> [!note] +> 以降の具体例では、簡単のため、HTML に限って本記事の趣旨から外れる記述(`class`等)を削ぎ落としている。 + +#### card + +まずカード単体の記法はこちら。 + +```markdown title="Markdown" +:::card +![younagi.dev](../../../assets/images/younagidev.jpg) +younagi.dev +::: +``` + +これがイイ感じの HTML に変換され・・。 + +```html title="HTML" +
+
+
+ + + + younagi.dev + +
younagi.dev
+
+
+
+ younagi.dev +
+
+``` + +最終的な出力はコレだ。 + +:::card +![younagi.dev](../../../assets/images/younagidev.jpg) +younagi.dev +::: + +#### card-grid + +次にカードグリッドの中に複数のカードを並べてみよう。 + +```markdown title="Markdown" +::::card-grid +:::card +![younagi.dev](../../../assets/images/younagidev.jpg) +younagi.dev 其の一 +::: +:::card +![younagi.dev](../../../assets/images/younagidev.jpg) +younagi.dev 其の二 +::: +:::card +![younagi.dev](../../../assets/images/younagidev.jpg) +younagi.dev 其の三 +::: +:::: +``` + +これが HTML に変換されると次のようになる。 + +```html title="HTML" +
+
+
+
+ + + + younagi.dev 其の一 + +
younagi.dev 其の一
+
+
+
+ younagi.dev 其の一 +
+
+
+
+
+ + + + younagi.dev 其の二 + +
younagi.dev 其の二
+
+
+
+ younagi.dev 其の二 +
+
+
+
+
+ + + + younagi.dev 其の三 + +
younagi.dev 其の三
+
+
+
+ younagi.dev 其の三 +
+
+
+``` + +そして最終的な出力はこちら。 + +::::card-grid +:::card +![younagi.dev](../../../assets/images/younagidev.jpg) +younagi.dev 其の一 +::: +:::card +![younagi.dev](../../../assets/images/younagidev.jpg) +younagi.dev 其の二 +::: +:::card +![younagi.dev](../../../assets/images/younagidev.jpg) +younagi.dev 其の三 +::: +:::: + +#### Astro で使う + +実は、当サイトでも既にカードコンポーネントが随所に鏤められている。 + +https://younagi.dev/ja/work/ + +Astro で Remark や Rehype のプラグインを利用するには、ルート直下にある専用のコンフィグファイルで下記の手続きが必要となる。 + +```ts title="astro.config.ts" {2,10-19} +import { defineConfig /* ... */ } from "astro/config"; +import remarkCard, { type Config as RemarkCardConfig } from 'remark-card'; +// ... + +export default defineConfig({ + // ... + markdown: { + remarkPlugins: [ + // ... + [ + remarkCard, + { + customHTMLTags: { + enabled: true, + }, + cardGridClass: 'card-grid', + cardClass: 'card', + } satisfies RemarkCardConfig, + ], + // ... + ], + // ... + } + // ... +}); +``` + +一応これだけでプラグインは動くようになるのだが、Astro コンポーネントを使って HTML タグやスタイルを細かく調整したい場合は、もうひと手間必要となる。 + +私の場合、`remark-card`によって`card`、`card-grid`タグに変換された箇所を、更にそれぞれ`Card.astro`、`CardGrid.astro`へと変換している。詳細は下記ソースコードを確認してほしい。 + +https://github.com/brklntmhwk/younagi.dev/tree/main/src/components/elements/Card + +そして [MDX の作法](https://docs.astro.build/ja/guides/integrations-guide/mdx/#custom-components-with-imported-mdx)に倣い、カスタムコンポーネントとして``タグにこれらを引き渡せば取引完了だ。下記がその一例である。 + +```ts title="~/lib/mdx-components.ts" +import { Card, CardGrid } from '@/components/elements/Card'; +// ... + +export const mdxComponents = { + // ... + card: Card, + 'card-grid': CardGrid, + // ... +}; +``` + +```astro title="~/pages/blog/[slug].astro" +--- +import BlogLayout from '@/layouts/BlogLayout.astro'; +import { mdxComponents } from '@/lib/mdx-components'; +import type { GetStaticPaths } from 'astro'; +// ... + +export const getStaticPaths = (async () => { + // ... +}) satisfies GetStaticPaths; + +const { entry } = Astro.props; +const { Content, headings } = await entry.render(); +--- + + + + +``` + +### 開発後記 + +このままでは README と書いてあることがほとんど変わらないので、技術選定について少し真面目に振り返ろうと思う。 + +- 言語: ~~JavaScript~~ TypeScript + - 型がないと生まれたての小鹿くらい足元が覚束なくなるため TypeScript で書くことにした + - ~~CommonJS~~ ESM の作法に倣って書いている +- マークダウン記法: [Generic directives/plugins syntax](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444) + - はじめは知る人が見たらひっくり返るようなド方言を編み出し、開発を進めていたが、より一般に浸透していそうなこちらの記法をチョイス + - `:::`や`::::`など +- テストランナー & パッケージマネージャ: [Bun](https://bun.sh/) + - JavaScript ランタイム、テストランナー、パッケージマネージャ、と複数の顔を併せ持つ肉まん君 + - テストコードが [Jest](https://jestjs.io/ja/) 互換で馴染みがあり、移行しやすい + - 目新しさとパフォーマンスの高さに惹かれ、採用 + +開発にあたり、先人たちの記したソースコードを浴びるように摂取したのだが、大半が JavaScript に JSDoc の組み合わせで書かれていた。 +製品コードを書く場合は総じてこの組み合わせの方が良いと思う [^2] が、今回は零細なプロジェクトなので慣れ親しんだ TypeScript で書くことにした。 + +[^2]: TypeScript で書かない為、トランスパイルの手間が省ける。しかし同時に、JSDoc の補助機能により型定義の恩恵に与ることもできる。 +更に JSDoc には元々ドキュメントの側面もあり、その作法に則って書くだけで読み手とコードの意図についてコミュニケーションが取りやすい。 + +## 結び + +実は`remark-card`の後、立て続けに`remark-video`という Remark プラグインも開発・リリースした。 + +https://github.com/brklntmhwk/remark-video + +当初はそちらも記事にしようと画策していたが、`remark-card`程の手間がかかっておらず、また本記事の執筆を以ってそこはかとない満足感に包まれてしまったため、断念した。[^3] + +[^3]: 有り体に言えば、面倒くさくなっただけである。 diff --git a/src/content/blog/ja/total-newbie-builds-mini-itx-linux-pc.mdx b/src/content/blog/ja/total-newbie-builds-mini-itx-linux-pc.mdx index 06cc7ebc..aab79f14 100644 --- a/src/content/blog/ja/total-newbie-builds-mini-itx-linux-pc.mdx +++ b/src/content/blog/ja/total-newbie-builds-mini-itx-linux-pc.mdx @@ -5,7 +5,7 @@ type: blog title: 【エラーだらけ】PC 自作初心者が Mini-ITX の Linux PC を組み立てる publishedAt: 2024-09-19T01:48:03.469Z fmContentType: blog -modifiedAt: 2024-11-25T08:16:29.979Z +modifiedAt: 2024-11-26T08:45:24.615Z category: metadata: ja/categories slug: attempt @@ -15,6 +15,7 @@ tags: - error - pc - nixos + - linux description: PC 自作初心者が無謀にも Mini-ITX PC の自作に挑戦した記録。パーツ選定からOSインストールまで、初心者目線でつまずいたポイントを解説する --- @@ -239,7 +240,7 @@ Linux OS のインストールも初めてだったからか、初めは自分 ![ Mini-ITX PC 完成 ](../../../assets/images/lian-li-a4-h2o-front-angle.JPEG) {/* textlint-disable ja-technical-writing/no-doubled-joshi */} -頂上が見えたあの瞬間 ー BIOS/UEFI メニューが初めてモニターに映し出された瞬間 ー の興奮は筆舌に尽くしがたい。 +頂上が見えたあの瞬間 —— BIOS/UEFI メニューが初めてモニターに映し出された瞬間 —— の興奮は筆舌に尽くしがたい。 この登頂記録が誰かの役に立つことを願っている。 diff --git a/src/content/tags/en/tags.yml b/src/content/tags/en/tags.yml index f2642db5..a0336e34 100644 --- a/src/content/tags/en/tags.yml +++ b/src/content/tags/en/tags.yml @@ -62,3 +62,12 @@ slug: electronics ruby: electronics color: green +- title: Markdown + slug: markdown + ruby: markdown + color: primary +- title: Linux + slug: linux + ruby: linux + color: gray + diff --git a/src/content/tags/ja/tags.yml b/src/content/tags/ja/tags.yml index ad9edeab..d394383d 100644 --- a/src/content/tags/ja/tags.yml +++ b/src/content/tags/ja/tags.yml @@ -62,3 +62,12 @@ slug: electronics ruby: でんしこうさく color: green +- slug: markdown + ruby: markdown + color: primary + title: Markdown +- slug: linux + ruby: linux + title: Linux + color: gray +