Next.js项目App目录如何简单集成markdown博客
<p>文章原文：Next.js项目App目录如何简单集成markdown博客</p><p>此教程适用于比较简单的项目实现，如果你是刚入门next，并且不想用太复杂的方式去实现一个博客项目，那么这个教程就挺适合你的。</p>
<p>Next.js官方关于markdown的文档有说明过如何渲染markdown，也是针对App目录的，但我尝试过并不太行，可能是版本的问题，不管怎么样，最后我并没有解决这个问题，而是用了别的方案去实现。</p>
<p>此教程适用于app目录的next项目，下面的例子刚好是多语言结构的项目。</p>
<h2 id="实现思路">实现思路</h2>
<p>结合文件结构解说一下大致逻辑：</p>
<p><img src="https://img2024.cnblogs.com/blog/1573343/202411/1573343-20241121214243387-1790193059.png"></p>
<p>Markdown文件放在<code>/app/_articles/</code>文件夹下管理，如果你是多语言目录，那么每个语种都是单独一个文件夹，如果不是，那么可以直接放在<code>/app/_articles</code>文件夹下。</p>
<p>另外markdown文件里从第一行开始可以放入一些Frontmatter，一般放在文件开头，用<code>---</code>符号分割开，提供一些额外信息，如发布时间、更新时间，是否已经发布，对应的描述，这类的信息可以自定义的，方便你做很多个性化的操作，一般我用来做meta信息的填充。</p>
<p>这里可以给一些Frontmatter的例子：</p>
<pre><code class="language-mdx">---
title: "这是博客标题"
createdAt: "2024-11-12"
updatedAt: "2024-11-12"
isPublished: true
description: "这是博客描述"
---
</code></pre>
<p>随着你文件的增多，你需要一些代码来管理、显示你的markdown信息，比如：</p>
<ol>
<li>在你的blog页面展示所有的markdown博客。</li>
<li>根据markdown文件名称跳转对应的博客详情，比如访问https://i18ncode.com/blog/how-nextjs-app-simply-make-i18n 能正常显示<code>how-nextjs-app-simply-make-i18n.mdx</code>文件内的文本。</li>
<li>渲染markdown文本，当然要包括对应页面的meta信息。</li>
</ol>
<h2 id="具体代码">具体代码</h2>
<p>大致要做的事情如上所述，下面贴对应的代码。</p>
<p>先封装好一些通用方法在<code>/lib/mdx.ts</code>文件中，方便后续调用：</p>
<pre><code class="language-ts">// mdx.ts
import fs from "fs";
import path from "path";
import matter from "gray-matter";
import readingTime from "reading-time";
const articlesDirectory = path.join(process.cwd(), "app/_articles");
const webContentDirectory = path.join(process.cwd(), "app/_contents");
// 获取 MDX/MD 原始数据
export function getMdxRawData(fileName: string, lang: string, hasSuffix: boolean) {
let fullPath = path.join(articlesDirectory, lang, `${fileName}`);
let suffix = hasSuffix // 判断是否有后缀，没有的话就加上后缀
? ""
: fs.existsSync(`${fullPath}.mdx`)
? ".mdx"
: ".md";
const fileContents = fs.readFileSync(`${fullPath}${suffix}`, "utf8");
return fileContents;
}
// 处理 MDX/MD 原始数据中的 frontmatter
export function getMdxFrontmatter(mdxRawData: string) {
const { content, data } = matter(mdxRawData);
return {
content,
frontmatter: data,
readingTime: readingTime(content).text, // 计算阅读时间
};
}
// 获取文章的所有信息
export function getArticlesData(fileName: string, lang: string, hasSuffix = false) {
return {
...getMdxFrontmatter(getMdxRawData(fileName, lang, hasSuffix)),
fileName: fileName.split(".").slice(0, -1).join("."), // 去除后缀
};
}
// 获取 _articles 目录下的所有文章
export function getAllArticlesData(lang: string) {
const fileNames = fs.readdirSync(articlesDirectory + "/" + lang);
const allArticlesData = fileNames.map((fileName) => {
return getArticlesData(fileName, lang,true);
});
return allArticlesData;
}
</code></pre>
<p>你可以根据你项目的具体情况来调整上面的代码。</p>
<h2 id="在你的blog页面展示所有的markdown博客">在你的blog页面展示所有的markdown博客</h2>
<p>调用上面封装好的<code>getAllArticlesData</code>方法，该方法支持一个叫lang的参数，这是多语言项目里有的参数，如果你传入的值为<code>en</code>，那么它就会去<code>/app/_articles/en</code>下获取所有的markdown文件。</p>
<p>然后不要忘记按时间排序：</p>
<pre><code class="language-ts">export default async function BlogPage({params: {lang}}: { params: { lang: Locale } }) {
const allArticlesData = getAllArticlesData(lang);
const dictionary = await getDictionary(lang);
const sortedArticles = allArticlesData.sort((a, b) => {
// 将日期字符串转换为日期对象
const dateA = new Date(a.frontmatter.createdAt).getTime();
const dateB = new Date(b.frontmatter.createdAt).getTime();
// 比较日期，返回值决定排序
return dateB - dateA; // 倒序排序
});
return (
<div>
<div className="mb-16">
<h1 className={title()}>{dictionary.blog.title}</h1>
<div className="mt-8">
{sortedArticles.map(article => (
<Blog blog={article} key={article.fileName} lang={lang} />
))}
</div>
</div>
<CallToAction dictionary={dictionary} />
</div>
);
}
</code></pre>
<h2 id="根据markdown文件名称跳转对应的博客详情">根据markdown文件名称跳转对应的博客详情</h2>
<p>Blog组件中使用简单的跳转：</p>
<pre><code class="language-ts"><Link href={`/${lang}/blog/${blog.fileName}`} />
</code></pre>
<p>将文件名传递过去，详情页面会根据文件名找到对应的文件进行渲染。</p>
<h2 id="渲染markdown文本">渲染markdown文本</h2>
<p>在<code>/app//blog//page.tsx</code>页面下则是对具体的markdown进行解析和渲染，将对应的内容填入页面，渲染meta信息：</p>
<pre><code class="language-ts">import { getArticlesData } from "@/lib/mdx";
import { Remarkable } from 'remarkable';
import hljs from 'highlight.js';
import {getDictionary} from "@/get-dictionaries";
import CallToAction from "@/components/cta";
import React from "react";
export const generateMetadata = async ({ params }: any) => {
const { content, frontmatter, readingTime } = getArticlesData(params.id, params.lang);
const lang = await getDictionary(params.lang);
return {
title: frontmatter.title + " | " + lang.blog.meta.title,
description: frontmatter.description,
openGraph: {
title: frontmatter.title + " | " + lang.blog.meta.title,
type: "website",
url: ``,
images: [
{
// 此处还可以有width和height属性，see:https://medium.com/@moh.mir36/open-graph-with-next-js-v13-app-directory-22c0049e2087
url: "/logo.png",
alt: ""
}
],
siteName: "",
description: frontmatter.description,
locale: ""
},
twitter: {
images: [
{
url: "/logo.png",
alt: ""
}
],
title: frontmatter.title + " | " + lang.blog.meta.title,
description: frontmatter.description,
card: "summary_large_image"
},
}
}
// !important：博客的排版需要在tailwind.config.js中添加插件：require("@tailwindcss/typography")，自行查看对应代码
const Page = async ({ params }: any) => {
const { content, frontmatter, readingTime } = getArticlesData(params.id, params.lang);
const md = new Remarkable({
html: true,
breaks: true,
linkify: true,
typographer: true,
highlight: function (str: string, lang: string) {
if (lang && hljs.getLanguage(lang)) {
try {
return hljs.highlight(lang, str).value;
} catch (err) {}
}
try {
return hljs.highlightAuto(str).value;
} catch (err) {
}
return ''; // use external default escaping
}
});
const blog = md.render(content, frontmatter);
const dictionary = await getDictionary(params.lang);
return (
<main className="container pb-24 text-start">
<div
className="prose dark:prose-invert prose-headings:mt-8 prose-headings:font-semibold prose-headings:text-black prose-h1:text-5xl prose-h2:text-4xl prose-h3:text-3xl prose-h4:text-2xl prose-h5:text-xl prose-h6:text-lg dark:prose-headings:text-white w-screen p-4">
<div dangerouslySetInnerHTML={{__html: blog}} className="prose-pre:p-4 dark:prose-pre:bg-gray-800 w-full p-4"/>
</div>
<CallToAction dictionary={dictionary} />
</main>
);
};
export default Page;
</code></pre>
<p>这里用了Remarkable方案代替了Next的MDXRemote组件。</p>
<p>到这里基本上完成了一半，但是样式方面可能会用欠缺，需要在<code>tailwind.config.js</code>中添加插件：<code>require("@tailwindcss/typography")</code>，代码如下：</p>
<pre><code class="language-js">import {nextui} from '@nextui-org/theme'
/** @type {import('tailwindcss').Config} */
module.exports = {
//...
plugins: [
// ....
require("@tailwindcss/typography"), // markdown typography
],
}
</code></pre>
<p>OK，到这里基本大功告成，就可以正常显示了，当然，<strong>过程中需要安装一些依赖，根据你项目里缺的依赖来安装就可以了</strong>。</p>
<h2 id="关于多语言markdown文件的管理和翻译">关于多语言Markdown文件的管理和翻译</h2>
<p>你可以看到，使用这种方式，如果是多语言的站点，那么你不可避免地要翻译和管理好对应的markdown文件。</p>
<p>用gpt翻译的话长度会受限制，第一个语种还好，第二个语种之后就会开始忘记原文，然后就开始胡言乱语了；要么你就每次对话都带上原文让gpt翻译，这样对话没几轮就得开启一个新的对话了。</p>
<p>我刚开始做这类工作的时候完成一篇博客需要一整个下午的时间，这实在是太耗时了。</p>
<p>机器翻译更无法接受，它无法识别markdown的符号，会格式错乱，另外机翻效果略显生硬。</p>
<p>基于这块的考虑我做了个专门针对这种情况的翻译器，有需要的朋友可以体验一下markdown翻译器。</p>
<p>markdown翻译器考虑了长度问题，做了文本切割并分段请求，你可以把一整个markdown文本塞进去翻译，直接获取最后的整体结果，经过反复尝试我这是没什么问题的；另外也做了markdown格式的识别和保留，不用害怕丢失格式；最后也考虑了本土化的情况，同样的文本也尽量要求AI用更本土化的方式表达出来，应该是比较适合做国际化的朋友了。</p>
<p>最后，感谢你阅读到这里，博客处会时不时更新一些独立开发的技术分享，希望能为更多的开发者朋友提供一些工具以外的帮助吧。</p><br><br>
来源：https://www.cnblogs.com/tandk-blog/p/18561598
頁:
[1]