feat: add locale extraction helper and new blog documentation
- Introduced `extractLocaleAndBase` function to streamline locale and base name extraction from filenames. - Added new blog documentation files covering comparisons, internationalization, manual installation, and markdown usage in both English and Chinese. - Removed outdated author and blog content files to enhance content organization and clarity. - Updated `content-collections.ts` to utilize the new locale extraction function for improved file handling.
This commit is contained in:
javayhu
parent
8a0c6d3631
commit
cd73bf8282
@ -38,6 +38,32 @@ const metas = defineCollection({
|
||||
schema: createMetaSchema,
|
||||
});
|
||||
|
||||
/**
|
||||
* Helper function to extract locale and base name from filename
|
||||
* Handles filename formats:
|
||||
* - name -> locale: DEFAULT_LOCALE, base: name
|
||||
* - name.zh -> locale: zh, base: name
|
||||
*
|
||||
* @param fileName Filename without extension (already has .mdx removed)
|
||||
* @returns Object with locale and base name
|
||||
*/
|
||||
function extractLocaleAndBase(fileName: string): { locale: string; base: string } {
|
||||
// Split filename into parts
|
||||
const parts = fileName.split('.');
|
||||
|
||||
if (parts.length === 1) {
|
||||
// Simple filename without locale: xxx
|
||||
return { locale: DEFAULT_LOCALE, base: parts[0] };
|
||||
} else if (parts.length === 2 && LOCALES.includes(parts[1])) {
|
||||
// Filename with locale: xxx.zh
|
||||
return { locale: parts[1], base: parts[0] };
|
||||
} else {
|
||||
// Unexpected format, use first part as base and default locale
|
||||
console.warn(`Unexpected filename format: ${fileName}`);
|
||||
return { locale: DEFAULT_LOCALE, base: parts[0] };
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Blog Author collection
|
||||
*
|
||||
@ -56,20 +82,14 @@ export const authors = defineCollection({
|
||||
locale: z.enum(LOCALES as [string, ...string[]]).optional()
|
||||
}),
|
||||
transform: async (data, context) => {
|
||||
// Determine the locale from the file name or use the provided locale
|
||||
const fileName = data._meta.path.split(path.sep).pop() || '';
|
||||
const fileNameParts = fileName.split('.');
|
||||
// Get the filename from the path
|
||||
const filePath = data._meta.path;
|
||||
const fileName = filePath.split(path.sep).pop() || '';
|
||||
|
||||
// Check if the file has a locale suffix (e.g., mksaas.zh.mdx)
|
||||
let localeFromFileName = null;
|
||||
if (fileNameParts.length > 2) {
|
||||
const possibleLocale = fileNameParts[fileNameParts.length - 2];
|
||||
if (LOCALES.includes(possibleLocale)) {
|
||||
localeFromFileName = possibleLocale;
|
||||
}
|
||||
}
|
||||
// Extract locale and base from filename
|
||||
const { locale, base } = extractLocaleAndBase(fileName);
|
||||
|
||||
const locale = data.locale || localeFromFileName || DEFAULT_LOCALE;
|
||||
console.log(`author processed: ${fileName}, locale=${locale}`);
|
||||
|
||||
return {
|
||||
...data,
|
||||
@ -96,20 +116,14 @@ export const categories = defineCollection({
|
||||
locale: z.enum(LOCALES as [string, ...string[]]).optional()
|
||||
}),
|
||||
transform: async (data, context) => {
|
||||
// Determine the locale from the file name or use the provided locale
|
||||
const fileName = data._meta.path.split(path.sep).pop() || '';
|
||||
const fileNameParts = fileName.split('.');
|
||||
// Get the filename from the path
|
||||
const filePath = data._meta.path;
|
||||
const fileName = filePath.split(path.sep).pop() || '';
|
||||
|
||||
// Check if the file has a locale suffix (e.g., tutorial.zh.mdx)
|
||||
let localeFromFileName = null;
|
||||
if (fileNameParts.length > 2) {
|
||||
const possibleLocale = fileNameParts[fileNameParts.length - 2];
|
||||
if (LOCALES.includes(possibleLocale)) {
|
||||
localeFromFileName = possibleLocale;
|
||||
}
|
||||
}
|
||||
// Extract locale and base from filename
|
||||
const { locale, base } = extractLocaleAndBase(fileName);
|
||||
|
||||
const locale = data.locale || localeFromFileName || DEFAULT_LOCALE;
|
||||
console.log(`category processed: ${fileName}, locale=${locale}`);
|
||||
|
||||
return {
|
||||
...data,
|
||||
@ -118,41 +132,6 @@ export const categories = defineCollection({
|
||||
}
|
||||
});
|
||||
|
||||
/**
|
||||
* Helper function to extract the file basename, locale, and extension
|
||||
* @param fileName The file name to parse
|
||||
* @returns Object with base, locale, and extension
|
||||
*/
|
||||
function parseFileName(fileName: string): { base: string; locale: string | null; ext: string } {
|
||||
// Split the filename into parts
|
||||
const parts = fileName.split('.');
|
||||
|
||||
// Handle different cases based on the number of parts
|
||||
if (parts.length === 1) {
|
||||
// Filename with no extension (unlikely)
|
||||
return { base: parts[0], locale: null, ext: '' };
|
||||
} else if (parts.length === 2) {
|
||||
// Regular filename with extension: example.mdx
|
||||
return { base: parts[0], locale: null, ext: parts[1] };
|
||||
} else {
|
||||
// Check if the second-to-last part is a locale
|
||||
const possibleLocale = parts[parts.length - 2];
|
||||
const isLocale = LOCALES.includes(possibleLocale);
|
||||
|
||||
if (isLocale) {
|
||||
// Filename with locale: example.zh.mdx
|
||||
// Join all parts except the last two with dots to handle filenames that contain dots
|
||||
const base = parts.slice(0, parts.length - 2).join('.');
|
||||
return { base, locale: possibleLocale, ext: parts[parts.length - 1] };
|
||||
} else {
|
||||
// Filename with dots but no locale: example.something.mdx
|
||||
// Join all parts except the last one with dots
|
||||
const base = parts.slice(0, parts.length - 1).join('.');
|
||||
return { base, locale: null, ext: parts[parts.length - 1] };
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Blog Post collection
|
||||
*
|
||||
@ -188,13 +167,13 @@ export const posts = defineCollection({
|
||||
const transformedData = await transformMDX(data, context);
|
||||
|
||||
// Get the filename from the path
|
||||
const fileName = data._meta.path.split(path.sep).pop() || '';
|
||||
const filePath = data._meta.path;
|
||||
const fileName = filePath.split(path.sep).pop() || '';
|
||||
|
||||
// Parse the filename into base, locale, and extension
|
||||
const { base, locale: localeFromFileName, ext } = parseFileName(fileName);
|
||||
// Extract locale and base from filename
|
||||
const { locale, base } = extractLocaleAndBase(fileName);
|
||||
|
||||
// Use the locale from the file name or fall back to default
|
||||
const locale = data.locale || localeFromFileName || DEFAULT_LOCALE;
|
||||
console.log(`post processed: ${fileName}, base=${base}, locale=${locale}`);
|
||||
|
||||
// Find the author by matching slug
|
||||
const blogAuthor = context
|
||||
@ -230,8 +209,6 @@ export const posts = defineCollection({
|
||||
const wordsPerMinute = 200; // average reading speed: 200 words per minute
|
||||
const estimatedTime = Math.max(Math.ceil(wordCount / wordsPerMinute), 1);
|
||||
|
||||
// console.log(`Post processed: ${fileName}, slugAsParams=${slugAsParams}, slug=${slug}`);
|
||||
|
||||
return {
|
||||
...data,
|
||||
locale,
|
||||
@ -240,7 +217,7 @@ export const posts = defineCollection({
|
||||
slug,
|
||||
slugAsParams,
|
||||
estimatedTime,
|
||||
body: transformedData.body, // Use processed MDX content directly
|
||||
body: transformedData.body,
|
||||
toc: transformedData.toc
|
||||
};
|
||||
}
|
||||
@ -277,13 +254,13 @@ export const pages = defineCollection({
|
||||
const transformedData = await transformMDX(data, context);
|
||||
|
||||
// Get the filename from the path
|
||||
const fileName = data._meta.path.split(path.sep).pop() || '';
|
||||
const filePath = data._meta.path;
|
||||
const fileName = filePath.split(path.sep).pop() || '';
|
||||
|
||||
// Parse the filename into base, locale, and extension
|
||||
const { base, locale: localeFromFileName, ext } = parseFileName(fileName);
|
||||
// Extract locale and base from filename
|
||||
const { locale, base } = extractLocaleAndBase(fileName);
|
||||
|
||||
// Use the locale from the file name or fall back to default
|
||||
const locale = data.locale || localeFromFileName || DEFAULT_LOCALE;
|
||||
console.log(`page processed: ${fileName}, base=${base}, locale=${locale}`);
|
||||
|
||||
// Get the collection name (e.g., "pages")
|
||||
const pathParts = data._meta.path.split(path.sep);
|
||||
@ -293,8 +270,6 @@ export const pages = defineCollection({
|
||||
const slug = `/${collectionName}/${base}`;
|
||||
const slugAsParams = base;
|
||||
|
||||
// console.log(`Page processed: ${fileName}, slugAsParams=${slugAsParams}, slug=${slug}`);
|
||||
|
||||
return {
|
||||
...data,
|
||||
locale,
|
||||
@ -338,13 +313,13 @@ export const releases = defineCollection({
|
||||
const transformedData = await transformMDX(data, context);
|
||||
|
||||
// Get the filename from the path
|
||||
const fileName = data._meta.path.split(path.sep).pop() || '';
|
||||
const filePath = data._meta.path;
|
||||
const fileName = filePath.split(path.sep).pop() || '';
|
||||
|
||||
// Parse the filename into base, locale, and extension
|
||||
const { base, locale: localeFromFileName, ext } = parseFileName(fileName);
|
||||
// Extract locale and base from filename
|
||||
const { locale, base } = extractLocaleAndBase(fileName);
|
||||
|
||||
// Use the locale from the file name or fall back to default
|
||||
const locale = data.locale || localeFromFileName || DEFAULT_LOCALE;
|
||||
console.log(`release processed: ${fileName}, base=${base}, locale=${locale}`);
|
||||
|
||||
// Get the collection name (e.g., "release")
|
||||
const pathParts = data._meta.path.split(path.sep);
|
||||
@ -354,8 +329,6 @@ export const releases = defineCollection({
|
||||
const slug = `/${collectionName}/${base}`;
|
||||
const slugAsParams = base;
|
||||
|
||||
// console.log(`Release processed: ${fileName}, slugAsParams=${slugAsParams}, slug=${slug}`);
|
||||
|
||||
return {
|
||||
...data,
|
||||
locale,
|
||||
|
||||
@ -1,5 +0,0 @@
|
||||
---
|
||||
slug: boilerplatehunt
|
||||
name: Boilerplate Hunt
|
||||
avatar: /images/avatars/boilerplatehunt.png
|
||||
---
|
||||
@ -1,5 +0,0 @@
|
||||
---
|
||||
slug: boilerplatehunt
|
||||
name: Boilerplate Hunt
|
||||
avatar: /images/avatars/boilerplatehunt.png
|
||||
---
|
||||
@ -1,5 +0,0 @@
|
||||
---
|
||||
slug: coupon
|
||||
name: Coupon
|
||||
avatar: /images/avatars/coupon.png
|
||||
---
|
||||
@ -1,5 +0,0 @@
|
||||
---
|
||||
slug: coupon
|
||||
name: Coupon
|
||||
avatar: /images/avatars/coupon.png
|
||||
---
|
||||
@ -1,5 +0,0 @@
|
||||
---
|
||||
slug: haitang
|
||||
name: HaiTang
|
||||
avatar: /images/avatars/haitang.png
|
||||
---
|
||||
@ -1,5 +0,0 @@
|
||||
---
|
||||
slug: haitang
|
||||
name: HaiTang
|
||||
avatar: /images/avatars/haitang.png
|
||||
---
|
||||
@ -1,5 +0,0 @@
|
||||
---
|
||||
slug: haitang
|
||||
name: HaiTang
|
||||
avatar: /images/avatars/indiehub.png
|
||||
---
|
||||
@ -1,5 +0,0 @@
|
||||
---
|
||||
slug: indiehub
|
||||
name: IndieHub
|
||||
avatar: /images/avatars/indiehub.png
|
||||
---
|
||||
@ -1,5 +0,0 @@
|
||||
---
|
||||
slug: oggenerator
|
||||
name: OG Generator
|
||||
avatar: /images/avatars/oggenerator.png
|
||||
---
|
||||
@ -1,5 +0,0 @@
|
||||
---
|
||||
slug: oggenerator
|
||||
name: OG Generator
|
||||
avatar: /images/avatars/oggenerator.png
|
||||
---
|
||||
78
content/blog/comparisons.mdx
Normal file
78
content/blog/comparisons.mdx
Normal file
@ -0,0 +1,78 @@
|
||||
---
|
||||
title: Comparisons
|
||||
description: How is Fumadocs different from other existing frameworks?
|
||||
image: /images/blog/mkdirs-og.png
|
||||
date: 2024-11-25T12:00:00.000Z
|
||||
published: true
|
||||
categories: [news, company]
|
||||
author: mkdirs
|
||||
---
|
||||
|
||||
## Nextra
|
||||
|
||||
Fumadocs is highly inspired by Nextra. For example, the Routing Conventions. That is why
|
||||
`meta.json` also exists in Fumadocs.
|
||||
|
||||
Nextra is more opinionated than Fumadocs. Fumadocs is accelerated by App Router. As a result, It provides many server-side functions, and you have to
|
||||
configure things manually compared to simply editing a configuration file.
|
||||
|
||||
Fumadocs works great if you want more control over everything, such as
|
||||
adding it to an existing codebase or implementing advanced routing.
|
||||
|
||||
### Feature Table
|
||||
|
||||
| Feature | Fumadocs | Nextra |
|
||||
| ------------------- | ------------ | ------------------------- |
|
||||
| Static Generation | Yes | Yes |
|
||||
| Cached | Yes | Yes |
|
||||
| Light/Dark Mode | Yes | Yes |
|
||||
| Syntax Highlighting | Yes | Yes |
|
||||
| Table of Contents | Yes | Yes |
|
||||
| Full-text Search | Yes | Yes |
|
||||
| i18n | Yes | Yes |
|
||||
| Last Git Edit Time | Yes | Yes |
|
||||
| Page Icons | Yes | Yes, via `_meta.js` files |
|
||||
| RSC | Yes | Yes |
|
||||
| Remote Source | Yes | Yes |
|
||||
| SEO | Via Metadata | Yes |
|
||||
| Built-in Components | Yes | Yes |
|
||||
| RTL Layout | Yes | Yes |
|
||||
|
||||
### Additional Features
|
||||
|
||||
Features supported via 3rd party libraries like [TypeDoc](https://typedoc.org) will not be listed here.
|
||||
|
||||
| Feature | Fumadocs | Nextra |
|
||||
| -------------------------- | -------- | ------ |
|
||||
| OpenAPI Integration | Yes | No |
|
||||
| TypeScript Docs Generation | Yes | No |
|
||||
| TypeScript Twoslash | Yes | Yes |
|
||||
|
||||
## Mintlify
|
||||
|
||||
Mintlify is a documentation service, as compared to Fumadocs, it offers a free tier but isn't completely free and open source.
|
||||
|
||||
Fumadocs is not as powerful as Mintlify, for example, the OpenAPI integration of Mintlify.
|
||||
As the creator of Fumadocs, I wouldn't recommend switching to Fumadocs from Mintlify if you're satisfied with the current way you build docs.
|
||||
However, I believe Fumadocs is a suitable tool for all Next.js developers who want to have elegant docs.
|
||||
|
||||
## Docusaurus
|
||||
|
||||
Docusaurus is a powerful framework based on React.js. It offers many cool
|
||||
features with plugins and custom themes.
|
||||
|
||||
### Better DX
|
||||
|
||||
Since Fumadocs is built on the top of Next.js, you'll have to start the Next.js dev
|
||||
server every time to review changes, and initial boilerplate code is relatively more
|
||||
compared to Docusaurus.
|
||||
|
||||
For a simple docs, Docusaurus might be a better choice if you don't need any Next.js specific functionality.
|
||||
|
||||
However, when you want to use Next.js, or seek extra customizability like tuning default UI components, Fumadocs could be a better choice.
|
||||
|
||||
### Plugins
|
||||
|
||||
You can easily achieve many things with plugins, their ecosystem is indeed larger and maintained by many contributors.
|
||||
|
||||
In comparison, the flexibility of Fumadocs allows you to implement them on your own, it may take longer to tune it to your satisfaction.
|
||||
72
content/blog/comparisons.zh.mdx
Normal file
72
content/blog/comparisons.zh.mdx
Normal file
@ -0,0 +1,72 @@
|
||||
---
|
||||
title: 对比
|
||||
description: Fumadocs 与其他现有框架有何不同？
|
||||
image: /images/blog/mkdirs-og.png
|
||||
date: 2024-11-25T12:00:00.000Z
|
||||
published: true
|
||||
categories: [news, company]
|
||||
author: mkdirs
|
||||
---
|
||||
|
||||
## Nextra
|
||||
|
||||
Fumadocs 深受 Nextra 启发。例如，路由约定。这就是为什么 Fumadocs 中也存在 `meta.json`。
|
||||
|
||||
Nextra 比 Fumadocs 更加固执己见。Fumadocs 由 App Router 加速。因此，它提供了许多服务器端功能，与简单编辑配置文件相比，您必须手动配置一些内容。
|
||||
|
||||
如果您想要对一切都有更多的控制，比如将其添加到现有代码库或实现高级路由，Fumadocs 会表现得很出色。
|
||||
|
||||
### 功能表
|
||||
|
||||
| 功能 | Fumadocs | Nextra |
|
||||
| ------------------- | ------------ | ------------------------- |
|
||||
| 静态生成 | 是 | 是 |
|
||||
| 缓存 | 是 | 是 |
|
||||
| 明/暗模式 | 是 | 是 |
|
||||
| 语法高亮 | 是 | 是 |
|
||||
| 目录 | 是 | 是 |
|
||||
| 全文搜索 | 是 | 是 |
|
||||
| 国际化 | 是 | 是 |
|
||||
| 最后 Git 编辑时间 | 是 | 是 |
|
||||
| 页面图标 | 是 | 是，通过 `_meta.js` 文件 |
|
||||
| RSC | 是 | 是 |
|
||||
| 远程源 | 是 | 是 |
|
||||
| SEO | 通过元数据 | 是 |
|
||||
| 内置组件 | 是 | 是 |
|
||||
| RTL 布局 | 是 | 是 |
|
||||
|
||||
### 附加功能
|
||||
|
||||
通过第三方库支持的功能（如 [TypeDoc](https://typedoc.org)）不会在此列出。
|
||||
|
||||
| 功能 | Fumadocs | Nextra |
|
||||
| -------------------------- | -------- | ------ |
|
||||
| OpenAPI 集成 | 是 | 否 |
|
||||
| TypeScript 文档生成 | 是 | 否 |
|
||||
| TypeScript Twoslash | 是 | 是 |
|
||||
|
||||
## Mintlify
|
||||
|
||||
Mintlify 是一项文档服务，与 Fumadocs 相比，它提供免费套餐，但并非完全免费和开源。
|
||||
|
||||
Fumadocs 不如 Mintlify 强大，例如 Mintlify 的 OpenAPI 集成。
|
||||
作为 Fumadocs 的创建者，如果您对当前构建文档的方式感到满意，我不建议从 Mintlify 切换到 Fumadocs。
|
||||
然而，我相信 Fumadocs 是所有想要拥有优雅文档的 Next.js 开发者的合适工具。
|
||||
|
||||
## Docusaurus
|
||||
|
||||
Docusaurus 是一个基于 React.js 的强大框架。它通过插件和自定义主题提供了许多酷炫的功能。
|
||||
|
||||
### 更好的开发者体验
|
||||
|
||||
由于 Fumadocs 构建在 Next.js 之上，您每次都必须启动 Next.js 开发服务器来查看更改，并且相对于 Docusaurus，初始样板代码较多。
|
||||
|
||||
对于简单的文档，如果您不需要任何特定于 Next.js 的功能，Docusaurus 可能是更好的选择。
|
||||
|
||||
然而，当您想要使用 Next.js，或寻求更多的可定制性，如调整默认 UI 组件时，Fumadocs 可能是更好的选择。
|
||||
|
||||
### 插件
|
||||
|
||||
您可以通过插件轻松实现许多功能，他们的生态系统确实更大，并由许多贡献者维护。
|
||||
|
||||
相比之下，Fumadocs 的灵活性允许您自己实现它们，可能需要更长的时间来调整它以达到您的满意度。
|
||||
227
content/blog/internationalization.mdx
Normal file
227
content/blog/internationalization.mdx
Normal file
@ -0,0 +1,227 @@
|
||||
---
|
||||
title: Internationalization
|
||||
description: Support multiple languages in your documentation
|
||||
image: /images/blog/mksaas-og.png
|
||||
date: 2024-11-26T12:00:00.000Z
|
||||
published: true
|
||||
categories: [company, product]
|
||||
author: mksaas
|
||||
---
|
||||
|
||||
<Callout title='Before you get started'>
|
||||
|
||||
Fumadocs is not a full-powered i18n library, it manages only its own components and utilities.
|
||||
|
||||
You can use other libraries like [next-intl](https://github.com/amannn/next-intl) for the rest of your app.
|
||||
Read the [Next.js Docs](https://nextjs.org/docs/app/building-your-application/routing/internationalization) to learn more about implementing I18n in Next.js.
|
||||
|
||||
</Callout>
|
||||
|
||||
## Manual Setup
|
||||
|
||||
Define the i18n configurations in a file, we will import it with `@/ilb/i18n` in this guide.
|
||||
|
||||
{/* <include cwd meta='title="lib/i18n.ts"'>
|
||||
../../examples/i18n/lib/i18n.ts
|
||||
</include> */}
|
||||
|
||||
Pass it to the source loader.
|
||||
|
||||
```ts title="lib/source.ts"
|
||||
import { i18n } from '@/lib/i18n';
|
||||
import { loader } from 'fumadocs-core/source';
|
||||
|
||||
export const source = loader({
|
||||
i18n, // [!code highlight]
|
||||
// other options
|
||||
});
|
||||
```
|
||||
|
||||
And update Fumadocs UI layout options.
|
||||
|
||||
```tsx title="app/layout.config.tsx"
|
||||
import { i18n } from '@/lib/i18n';
|
||||
import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
|
||||
|
||||
export function baseOptions(locale: string): BaseLayoutProps {
|
||||
return {
|
||||
i18n,
|
||||
// different props based on `locale`
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Middleware
|
||||
|
||||
Create a middleware that redirects users to appropriate locale.
|
||||
|
||||
```json doc-gen:file
|
||||
{
|
||||
"file": "../../examples/i18n/middleware.ts",
|
||||
"codeblock": {
|
||||
"lang": "ts",
|
||||
"meta": "title=\"middleware.ts\""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See [Middleware](/docs/headless/internationalization#middleware) for customisable options.
|
||||
|
||||
> Note that this is optional, you can also use your own middleware or the one provided by i18n libraries.
|
||||
|
||||
### Routing
|
||||
|
||||
Create a `/app/[lang]` folder, and move all files (e.g. `page.tsx`, `layout.tsx`) from `/app` to the folder.
|
||||
|
||||
Wrap the root provider inside `I18nProvider`, and provide available languages & translations to it.
|
||||
Note that only English translations are provided by default.
|
||||
|
||||
```tsx title="app/[lang]/layout.tsx"
|
||||
import { RootProvider } from 'fumadocs-ui/provider';
|
||||
import { I18nProvider, type Translations } from 'fumadocs-ui/i18n';
|
||||
|
||||
const cn: Partial<Translations> = {
|
||||
search: 'Translated Content',
|
||||
// other translations
|
||||
};
|
||||
|
||||
// available languages that will be displayed on UI
|
||||
// make sure `locale` is consistent with your i18n config
|
||||
const locales = [
|
||||
{
|
||||
name: 'English',
|
||||
locale: 'en',
|
||||
},
|
||||
{
|
||||
name: 'Chinese',
|
||||
locale: 'cn',
|
||||
},
|
||||
];
|
||||
|
||||
export default async function RootLayout({
|
||||
params,
|
||||
children,
|
||||
}: {
|
||||
params: Promise<{ lang: string }>;
|
||||
children: React.ReactNode;
|
||||
}) {
|
||||
const lang = (await params).lang;
|
||||
|
||||
return (
|
||||
<html lang={lang}>
|
||||
<body>
|
||||
<I18nProvider
|
||||
locale={lang}
|
||||
locales={locales}
|
||||
translations={{ cn }[lang]}
|
||||
>
|
||||
<RootProvider>{children}</RootProvider>
|
||||
</I18nProvider>
|
||||
</body>
|
||||
</html>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Pass Locale
|
||||
|
||||
Pass the locale to Fumadocs in your pages and layouts.
|
||||
|
||||
{/* ```tsx title="/app/[lang]/(home)/layout.tsx" tab="Home Layout"
|
||||
import type { ReactNode } from 'react';
|
||||
import { HomeLayout } from 'fumadocs-ui/layouts/home';
|
||||
import { baseOptions } from '@/app/layout.config';
|
||||
|
||||
export default async function Layout({
|
||||
params,
|
||||
children,
|
||||
}: {
|
||||
params: Promise<{ lang: string }>;
|
||||
children: ReactNode;
|
||||
}) {
|
||||
const { lang } = await params;
|
||||
|
||||
return <HomeLayout {...baseOptions(lang)}>{children}</HomeLayout>;
|
||||
}
|
||||
```
|
||||
|
||||
```tsx title="/app/[lang]/docs/layout.tsx" tab="Docs Layout"
|
||||
import type { ReactNode } from 'react';
|
||||
import { source } from '@/lib/source';
|
||||
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
|
||||
import { baseOptions } from '@/app/layout.config';
|
||||
|
||||
export default async function Layout({
|
||||
params,
|
||||
children,
|
||||
}: {
|
||||
params: Promise<{ lang: string }>;
|
||||
children: ReactNode;
|
||||
}) {
|
||||
const { lang } = await params;
|
||||
|
||||
return (
|
||||
<DocsLayout {...baseOptions(lang)} tree={source.pageTree[lang]}>
|
||||
{children}
|
||||
</DocsLayout>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
```ts title="page.tsx" tab="Docs Page"
|
||||
import { source } from '@/lib/source';
|
||||
|
||||
export default async function Page({
|
||||
params,
|
||||
}: {
|
||||
params: Promise<{ lang: string; slug?: string[] }>;
|
||||
}) {
|
||||
const { slug, lang } = await params;
|
||||
// get page
|
||||
source.getPage(slug); // [!code --]
|
||||
source.getPage(slug, lang); // [!code ++]
|
||||
|
||||
// get pages
|
||||
source.getPages(); // [!code --]
|
||||
source.getPages(lang); // [!code ++]
|
||||
}
|
||||
``` */}
|
||||
|
||||
### Search
|
||||
|
||||
Configure i18n on your search solution.
|
||||
|
||||
- **Built-in Search (Orama):**
|
||||
For [Supported Languages](https://docs.orama.com/open-source/supported-languages#officially-supported-languages), no further changes are needed.
|
||||
|
||||
Otherwise, additional config is required (e.g. Chinese & Japanese). See [Special Languages](/docs/headless/search/orama#special-languages).
|
||||
|
||||
- **Cloud Solutions (e.g. Algolia):**
|
||||
They usually have official support for multilingual.
|
||||
|
||||
## Writing Documents
|
||||
|
||||
{/* <include>../../shared/page-conventions.i18n.mdx</include> */}
|
||||
|
||||
## Navigation
|
||||
|
||||
Fumadocs only handles navigation for its own layouts (e.g. sidebar).
|
||||
For other places, you can use the `useParams` hook to get the locale from url, and attend it to `href`.
|
||||
|
||||
```tsx
|
||||
import Link from 'next/link';
|
||||
import { useParams } from 'next/navigation';
|
||||
|
||||
const { lang } = useParams();
|
||||
|
||||
return <Link href={`/${lang}/another-page`}>This is a link</Link>;
|
||||
```
|
||||
|
||||
In addition, the [`fumadocs-core/dynamic-link`](/docs/headless/components/link#dynamic-hrefs) component supports dynamic hrefs, you can use it to attend the locale prefix.
|
||||
It is useful for Markdown/MDX content.
|
||||
|
||||
```mdx title="content.mdx"
|
||||
import { DynamicLink } from 'fumadocs-core/dynamic-link';
|
||||
|
||||
<DynamicLink href="/[lang]/another-page">This is a link</DynamicLink>
|
||||
```
|
||||
227
content/blog/internationalization.zh.mdx
Normal file
227
content/blog/internationalization.zh.mdx
Normal file
@ -0,0 +1,227 @@
|
||||
---
|
||||
title: 国际化
|
||||
description: 在您的文档中支持多种语言
|
||||
image: /images/blog/mksaas-og.png
|
||||
date: 2024-11-26T12:00:00.000Z
|
||||
published: true
|
||||
categories: [company, product]
|
||||
author: mksaas
|
||||
---
|
||||
|
||||
<Callout title='开始之前'>
|
||||
|
||||
Fumadocs 不是一个功能齐全的 i18n 库，它只管理自己的组件和工具。
|
||||
|
||||
您可以使用其他库，如 [next-intl](https://github.com/amannn/next-intl)，用于应用程序的其余部分。
|
||||
阅读 [Next.js 文档](https://nextjs.org/docs/app/building-your-application/routing/internationalization)，了解更多关于在 Next.js 中实现 I18n 的信息。
|
||||
|
||||
</Callout>
|
||||
|
||||
## 手动设置
|
||||
|
||||
在一个文件中定义 i18n 配置，我们将在本指南中使用 `@/ilb/i18n` 导入它。
|
||||
|
||||
{/* <include cwd meta='title="lib/i18n.ts"'>
|
||||
../../examples/i18n/lib/i18n.ts
|
||||
</include> */}
|
||||
|
||||
将其传递给源加载器。
|
||||
|
||||
```ts title="lib/source.ts"
|
||||
import { i18n } from '@/lib/i18n';
|
||||
import { loader } from 'fumadocs-core/source';
|
||||
|
||||
export const source = loader({
|
||||
i18n, // [!code highlight]
|
||||
// other options
|
||||
});
|
||||
```
|
||||
|
||||
并更新 Fumadocs UI 布局选项。
|
||||
|
||||
```tsx title="app/layout.config.tsx"
|
||||
import { i18n } from '@/lib/i18n';
|
||||
import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
|
||||
|
||||
export function baseOptions(locale: string): BaseLayoutProps {
|
||||
return {
|
||||
i18n,
|
||||
// different props based on `locale`
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### 中间件
|
||||
|
||||
创建一个将用户重定向到适当语言环境的中间件。
|
||||
|
||||
```json doc-gen:file
|
||||
{
|
||||
"file": "../../examples/i18n/middleware.ts",
|
||||
"codeblock": {
|
||||
"lang": "ts",
|
||||
"meta": "title=\"middleware.ts\""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
查看[中间件](/docs/headless/internationalization#middleware)了解可自定义选项。
|
||||
|
||||
> 请注意，这是可选的，您也可以使用自己的中间件或 i18n 库提供的中间件。
|
||||
|
||||
### 路由
|
||||
|
||||
创建一个 `/app/[lang]` 文件夹，并将所有文件（例如 `page.tsx`、`layout.tsx`）从 `/app` 移动到该文件夹。
|
||||
|
||||
将根提供程序包装在 `I18nProvider` 中，并向其提供可用语言和翻译。
|
||||
请注意，默认情况下只提供英文翻译。
|
||||
|
||||
```tsx title="app/[lang]/layout.tsx"
|
||||
import { RootProvider } from 'fumadocs-ui/provider';
|
||||
import { I18nProvider, type Translations } from 'fumadocs-ui/i18n';
|
||||
|
||||
const cn: Partial<Translations> = {
|
||||
search: 'Translated Content',
|
||||
// other translations
|
||||
};
|
||||
|
||||
// available languages that will be displayed on UI
|
||||
// make sure `locale` is consistent with your i18n config
|
||||
const locales = [
|
||||
{
|
||||
name: 'English',
|
||||
locale: 'en',
|
||||
},
|
||||
{
|
||||
name: 'Chinese',
|
||||
locale: 'cn',
|
||||
},
|
||||
];
|
||||
|
||||
export default async function RootLayout({
|
||||
params,
|
||||
children,
|
||||
}: {
|
||||
params: Promise<{ lang: string }>;
|
||||
children: React.ReactNode;
|
||||
}) {
|
||||
const lang = (await params).lang;
|
||||
|
||||
return (
|
||||
<html lang={lang}>
|
||||
<body>
|
||||
<I18nProvider
|
||||
locale={lang}
|
||||
locales={locales}
|
||||
translations={{ cn }[lang]}
|
||||
>
|
||||
<RootProvider>{children}</RootProvider>
|
||||
</I18nProvider>
|
||||
</body>
|
||||
</html>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### 传递区域设置
|
||||
|
||||
在您的页面和布局中将区域设置传递给 Fumadocs。
|
||||
|
||||
{/* ```tsx title="/app/[lang]/(home)/layout.tsx" tab="Home Layout"
|
||||
import type { ReactNode } from 'react';
|
||||
import { HomeLayout } from 'fumadocs-ui/layouts/home';
|
||||
import { baseOptions } from '@/app/layout.config';
|
||||
|
||||
export default async function Layout({
|
||||
params,
|
||||
children,
|
||||
}: {
|
||||
params: Promise<{ lang: string }>;
|
||||
children: ReactNode;
|
||||
}) {
|
||||
const { lang } = await params;
|
||||
|
||||
return <HomeLayout {...baseOptions(lang)}>{children}</HomeLayout>;
|
||||
}
|
||||
```
|
||||
|
||||
```tsx title="/app/[lang]/docs/layout.tsx" tab="Docs Layout"
|
||||
import type { ReactNode } from 'react';
|
||||
import { source } from '@/lib/source';
|
||||
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
|
||||
import { baseOptions } from '@/app/layout.config';
|
||||
|
||||
export default async function Layout({
|
||||
params,
|
||||
children,
|
||||
}: {
|
||||
params: Promise<{ lang: string }>;
|
||||
children: ReactNode;
|
||||
}) {
|
||||
const { lang } = await params;
|
||||
|
||||
return (
|
||||
<DocsLayout {...baseOptions(lang)} tree={source.pageTree[lang]}>
|
||||
{children}
|
||||
</DocsLayout>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
```ts title="page.tsx" tab="Docs Page"
|
||||
import { source } from '@/lib/source';
|
||||
|
||||
export default async function Page({
|
||||
params,
|
||||
}: {
|
||||
params: Promise<{ lang: string; slug?: string[] }>;
|
||||
}) {
|
||||
const { slug, lang } = await params;
|
||||
// get page
|
||||
source.getPage(slug); // [!code --]
|
||||
source.getPage(slug, lang); // [!code ++]
|
||||
|
||||
// get pages
|
||||
source.getPages(); // [!code --]
|
||||
source.getPages(lang); // [!code ++]
|
||||
}
|
||||
``` */}
|
||||
|
||||
### 搜索
|
||||
|
||||
在您的搜索解决方案上配置 i18n。
|
||||
|
||||
- **内置搜索 (Orama)：**
|
||||
对于[支持的语言](https://docs.orama.com/open-source/supported-languages#officially-supported-languages)，无需进一步更改。
|
||||
|
||||
否则，需要额外配置（例如中文和日语）。请参阅[特殊语言](/docs/headless/search/orama#special-languages)。
|
||||
|
||||
- **云解决方案（例如 Algolia）：**
|
||||
它们通常官方支持多语言。
|
||||
|
||||
## 编写文档
|
||||
|
||||
{/* <include>../../shared/page-conventions.i18n.mdx</include> */}
|
||||
|
||||
## 导航
|
||||
|
||||
Fumadocs 只处理其自己的布局（例如侧边栏）的导航。
|
||||
对于其他地方，您可以使用 `useParams` 钩子从 url 获取区域设置，并将其添加到 `href`。
|
||||
|
||||
```tsx
|
||||
import Link from 'next/link';
|
||||
import { useParams } from 'next/navigation';
|
||||
|
||||
const { lang } = useParams();
|
||||
|
||||
return <Link href={`/${lang}/another-page`}>This is a link</Link>;
|
||||
```
|
||||
|
||||
另外，[`fumadocs-core/dynamic-link`](/docs/headless/components/link#dynamic-hrefs) 组件支持动态 hrefs，您可以使用它来添加区域设置前缀。
|
||||
这对于 Markdown/MDX 内容很有用。
|
||||
|
||||
```mdx title="content.mdx"
|
||||
import { DynamicLink } from 'fumadocs-core/dynamic-link';
|
||||
|
||||
<DynamicLink href="/[lang]/another-page">This is a link</DynamicLink>
|
||||
```
|
||||
190
content/blog/manual-installation.mdx
Normal file
190
content/blog/manual-installation.mdx
Normal file
@ -0,0 +1,190 @@
|
||||
---
|
||||
title: Manual Installation
|
||||
description: Create a new fumadocs project from scratch.
|
||||
image: /images/blog/mksaas-og.png
|
||||
date: 2025-03-31T12:00:00.000Z
|
||||
published: true
|
||||
categories: [company, product]
|
||||
author: mksaas
|
||||
---
|
||||
|
||||
> Read the [Quick Start](/docs) guide first for basic concept.
|
||||
|
||||
## Getting Started
|
||||
|
||||
Create a new Next.js application with `create-next-app`, and install required packages.
|
||||
|
||||
```package-install
|
||||
fumadocs-ui fumadocs-core
|
||||
```
|
||||
|
||||
### Content Source
|
||||
|
||||
Fumadocs supports different content sources, you can choose one you prefer.
|
||||
|
||||
There is a list of officially supported sources:
|
||||
|
||||
- [Setup Fumadocs MDX](/docs/mdx)
|
||||
- [Setup Content Collections](/docs/headless/content-collections)
|
||||
|
||||
Make sure to configure the library correctly following their setup guide before continuing, we will import the source adapter using `@/lib/source.ts` in this guide.
|
||||
|
||||
### Root Layout
|
||||
|
||||
Wrap the entire application inside [Root Provider](/docs/layouts/root-provider), and add required styles to `body`.
|
||||
|
||||
```tsx
|
||||
import { RootProvider } from 'fumadocs-ui/provider';
|
||||
import type { ReactNode } from 'react';
|
||||
|
||||
export default function Layout({ children }: { children: ReactNode }) {
|
||||
return (
|
||||
<html lang="en" suppressHydrationWarning>
|
||||
<body
|
||||
// you can use Tailwind CSS too
|
||||
style={{
|
||||
display: 'flex',
|
||||
flexDirection: 'column',
|
||||
minHeight: '100vh',
|
||||
}}
|
||||
>
|
||||
<RootProvider>{children}</RootProvider>
|
||||
</body>
|
||||
</html>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Styles
|
||||
|
||||
Setup Tailwind CSS v4 on your Next.js app, add the following to `global.css`.
|
||||
|
||||
```css title="Tailwind CSS"
|
||||
@import 'tailwindcss';
|
||||
@import 'fumadocs-ui/css/neutral.css';
|
||||
@import 'fumadocs-ui/css/preset.css';
|
||||
|
||||
/* path of `fumadocs-ui` relative to the CSS file */
|
||||
@source '../node_modules/fumadocs-ui/dist/**/*.js';
|
||||
```
|
||||
|
||||
> It doesn't come with a default font, you may choose one from `next/font`.
|
||||
|
||||
### Layout
|
||||
|
||||
Create a `app/layout.config.tsx` file to put the shared options for our layouts.
|
||||
|
||||
```json doc-gen:file
|
||||
{
|
||||
"file": "../../examples/next-mdx/app/layout.config.tsx",
|
||||
"codeblock": {
|
||||
"meta": "title=\"app/layout.config.tsx\""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Create a folder `/app/docs` for our docs, and give it a proper layout.
|
||||
|
||||
```json doc-gen:file
|
||||
{
|
||||
"file": "../../examples/next-mdx/app/docs/layout.tsx",
|
||||
"codeblock": {
|
||||
"meta": "title=\"app/docs/layout.tsx\""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> `pageTree` refers to Page Tree, it should be provided by your content source.
|
||||
|
||||
### Page
|
||||
|
||||
Create a catch-all route `/app/docs/[[...slug]]` for docs pages.
|
||||
|
||||
In the page, wrap your content in the [Page](/docs/layouts/page) component.
|
||||
It may vary depending on your content source. You should configure static rendering with `generateStaticParams` and metadata with `generateMetadata`.
|
||||
|
||||
<Tabs groupId='content-source' items={['Fumadocs MDX', 'Content Collections']}>
|
||||
|
||||
```json doc-gen:file
|
||||
{
|
||||
"file": "../../examples/next-mdx/app/docs/[[...slug]]/page.tsx",
|
||||
"codeblock": {
|
||||
"meta": "title=\"app/docs/[[...slug]]/page.tsx\" tab=\"Fumadocs MDX\""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json doc-gen:file
|
||||
{
|
||||
"file": "../../examples/content-collections/app/docs/[[...slug]]/page.tsx",
|
||||
"codeblock": {
|
||||
"meta": "title=\"app/docs/[[...slug]]/page.tsx\" tab=\"Content Collections\""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</Tabs>
|
||||
|
||||
### Search
|
||||
|
||||
Use the default document search based on Orama.
|
||||
|
||||
<Tabs groupId='content-source' items={['Fumadocs MDX', 'Content Collections']}>
|
||||
|
||||
```json doc-gen:file
|
||||
{
|
||||
"file": "../../examples/next-mdx/app/api/search/route.ts",
|
||||
"codeblock": {
|
||||
"meta": "title=\"app/api/search/route.ts\" tab=\"Fumadocs MDX\""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json doc-gen:file
|
||||
{
|
||||
"file": "../../examples/content-collections/app/api/search/route.ts",
|
||||
"codeblock": {
|
||||
"meta": "title=\"app/api/search/route.ts\" tab=\"Content Collections\""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</Tabs>
|
||||
|
||||
Learn more about [Document Search](/docs/headless/search).
|
||||
|
||||
### Done
|
||||
|
||||
You can start the dev server and create MDX files.
|
||||
|
||||
```mdx title="content/docs/index.mdx"
|
||||
---
|
||||
title: Hello World
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
I love Anime.
|
||||
```
|
||||
|
||||
## Customise
|
||||
|
||||
You can use [Home Layout](/docs/layouts/home-layout) for other pages of the site, it includes a navbar with theme toggle.
|
||||
|
||||
## Deploying
|
||||
|
||||
It should work out-of-the-box with Vercel & Netlify.
|
||||
|
||||
### Docker Deployment
|
||||
|
||||
If you want to deploy your Fumadocs app using Docker with **Fumadocs MDX configured**, make sure to add the `source.config.ts` file to the `WORKDIR` in the Dockerfile.
|
||||
The following snippet is taken from the official [Next.js Dockerfile Example](https://github.com/vercel/next.js/blob/canary/examples/with-docker/Dockerfile):
|
||||
|
||||
```zsh title="Dockerfile"
|
||||
WORKDIR /app
|
||||
|
||||
# Install dependencies based on the preferred package manager
|
||||
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* source.config.ts ./
|
||||
```
|
||||
|
||||
This ensures Fumadocs MDX can access your configuration file during builds.
|
||||
190
content/blog/manual-installation.zh.mdx
Normal file
190
content/blog/manual-installation.zh.mdx
Normal file
@ -0,0 +1,190 @@
|
||||
---
|
||||
title: 手动安装
|
||||
description: 从零开始创建一个新的 Fumadocs 项目
|
||||
image: /images/blog/mksaas-og.png
|
||||
date: 2025-03-31T12:00:00.000Z
|
||||
published: true
|
||||
categories: [company, product]
|
||||
author: mksaas
|
||||
---
|
||||
|
||||
> 请先阅读[快速入门](/docs)指南了解基本概念。
|
||||
|
||||
## 入门
|
||||
|
||||
使用 `create-next-app` 创建一个新的 Next.js 应用程序，并安装所需的包。
|
||||
|
||||
```package-install
|
||||
fumadocs-ui fumadocs-core
|
||||
```
|
||||
|
||||
### 内容源
|
||||
|
||||
Fumadocs 支持不同的内容源，您可以选择您喜欢的一种。
|
||||
|
||||
以下是官方支持的源列表：
|
||||
|
||||
- [设置 Fumadocs MDX](/docs/mdx)
|
||||
- [设置 Content Collections](/docs/headless/content-collections)
|
||||
|
||||
请确保在继续之前按照其设置指南正确配置库，我们将在本指南中使用 `@/lib/source.ts` 导入源适配器。
|
||||
|
||||
### 根布局
|
||||
|
||||
将整个应用程序包装在 [Root Provider](/docs/layouts/root-provider) 中，并为 `body` 添加所需的样式。
|
||||
|
||||
```tsx
|
||||
import { RootProvider } from 'fumadocs-ui/provider';
|
||||
import type { ReactNode } from 'react';
|
||||
|
||||
export default function Layout({ children }: { children: ReactNode }) {
|
||||
return (
|
||||
<html lang="en" suppressHydrationWarning>
|
||||
<body
|
||||
// you can use Tailwind CSS too
|
||||
style={{
|
||||
display: 'flex',
|
||||
flexDirection: 'column',
|
||||
minHeight: '100vh',
|
||||
}}
|
||||
>
|
||||
<RootProvider>{children}</RootProvider>
|
||||
</body>
|
||||
</html>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### 样式
|
||||
|
||||
在您的 Next.js 应用程序上设置 Tailwind CSS v4，将以下内容添加到 `global.css`。
|
||||
|
||||
```css title="Tailwind CSS"
|
||||
@import 'tailwindcss';
|
||||
@import 'fumadocs-ui/css/neutral.css';
|
||||
@import 'fumadocs-ui/css/preset.css';
|
||||
|
||||
/* path of `fumadocs-ui` relative to the CSS file */
|
||||
@source '../node_modules/fumadocs-ui/dist/**/*.js';
|
||||
```
|
||||
|
||||
> 它不附带默认字体，您可以从 `next/font` 中选择一个。
|
||||
|
||||
### 布局
|
||||
|
||||
创建一个 `app/layout.config.tsx` 文件，放置我们布局的共享选项。
|
||||
|
||||
```json doc-gen:file
|
||||
{
|
||||
"file": "../../examples/next-mdx/app/layout.config.tsx",
|
||||
"codeblock": {
|
||||
"meta": "title=\"app/layout.config.tsx\""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
为我们的文档创建一个文件夹 `/app/docs`，并给它一个适当的布局。
|
||||
|
||||
```json doc-gen:file
|
||||
{
|
||||
"file": "../../examples/next-mdx/app/docs/layout.tsx",
|
||||
"codeblock": {
|
||||
"meta": "title=\"app/docs/layout.tsx\""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> `pageTree` 指的是页面树，应该由您的内容源提供。
|
||||
|
||||
### 页面
|
||||
|
||||
为文档页面创建一个捕获所有路由 `/app/docs/[[...slug]]`。
|
||||
|
||||
在页面中，将您的内容包装在 [Page](/docs/layouts/page) 组件中。
|
||||
这可能因您的内容源而异。您应该使用 `generateStaticParams` 配置静态渲染，并使用 `generateMetadata` 配置元数据。
|
||||
|
||||
<Tabs groupId='content-source' items={['Fumadocs MDX', 'Content Collections']}>
|
||||
|
||||
```json doc-gen:file
|
||||
{
|
||||
"file": "../../examples/next-mdx/app/docs/[[...slug]]/page.tsx",
|
||||
"codeblock": {
|
||||
"meta": "title=\"app/docs/[[...slug]]/page.tsx\" tab=\"Fumadocs MDX\""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json doc-gen:file
|
||||
{
|
||||
"file": "../../examples/content-collections/app/docs/[[...slug]]/page.tsx",
|
||||
"codeblock": {
|
||||
"meta": "title=\"app/docs/[[...slug]]/page.tsx\" tab=\"Content Collections\""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</Tabs>
|
||||
|
||||
### 搜索
|
||||
|
||||
使用基于 Orama 的默认文档搜索。
|
||||
|
||||
<Tabs groupId='content-source' items={['Fumadocs MDX', 'Content Collections']}>
|
||||
|
||||
```json doc-gen:file
|
||||
{
|
||||
"file": "../../examples/next-mdx/app/api/search/route.ts",
|
||||
"codeblock": {
|
||||
"meta": "title=\"app/api/search/route.ts\" tab=\"Fumadocs MDX\""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json doc-gen:file
|
||||
{
|
||||
"file": "../../examples/content-collections/app/api/search/route.ts",
|
||||
"codeblock": {
|
||||
"meta": "title=\"app/api/search/route.ts\" tab=\"Content Collections\""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</Tabs>
|
||||
|
||||
了解更多关于[文档搜索](/docs/headless/search)的信息。
|
||||
|
||||
### 完成
|
||||
|
||||
您可以启动开发服务器并创建 MDX 文件。
|
||||
|
||||
```mdx title="content/docs/index.mdx"
|
||||
---
|
||||
title: Hello World
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
I love Anime.
|
||||
```
|
||||
|
||||
## 自定义
|
||||
|
||||
您可以为网站的其他页面使用 [Home Layout](/docs/layouts/home-layout)，它包含一个带有主题切换的导航栏。
|
||||
|
||||
## 部署
|
||||
|
||||
它应该在 Vercel 和 Netlify 上开箱即用。
|
||||
|
||||
### Docker 部署
|
||||
|
||||
如果您想使用 Docker 部署您的 Fumadocs 应用程序，并且已**配置了 Fumadocs MDX**，请确保将 `source.config.ts` 文件添加到 Dockerfile 中的 `WORKDIR`。
|
||||
以下片段取自官方 [Next.js Dockerfile 示例](https://github.com/vercel/next.js/blob/canary/examples/with-docker/Dockerfile)：
|
||||
|
||||
```zsh title="Dockerfile"
|
||||
WORKDIR /app
|
||||
|
||||
# Install dependencies based on the preferred package manager
|
||||
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* source.config.ts ./
|
||||
```
|
||||
|
||||
这确保 Fumadocs MDX 在构建期间可以访问您的配置文件。
|
||||
373
content/blog/markdown.mdx
Normal file
373
content/blog/markdown.mdx
Normal file
@ -0,0 +1,373 @@
|
||||
---
|
||||
title: Markdown
|
||||
description: How to write documents
|
||||
image: /images/blog/mkdirs-og.png
|
||||
date: 2024-11-25T12:00:00.000Z
|
||||
published: true
|
||||
categories: [news, company]
|
||||
author: mkdirs
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
Fumadocs provides many useful extensions to MDX, a markup language. Here is a brief introduction to the default MDX syntax of Fumadocs UI.
|
||||
|
||||
> MDX is not the only supported format of Fumadocs. In fact, you can use any renderers such as `next-mdx-remote` or CMS.
|
||||
|
||||
## Markdown
|
||||
|
||||
We use GFM (GitHub Flavored Markdown), a superset of Markdown (CommonMark).
|
||||
See [GFM Specification](https://github.github.com/gfm).
|
||||
|
||||
````md
|
||||
# Heading
|
||||
|
||||
## Heading
|
||||
|
||||
### Heading
|
||||
|
||||
#### Heading
|
||||
|
||||
Hello World, **Bold**, _Italic_, ~~Hidden~~
|
||||
|
||||
```js
|
||||
console.log('Hello World');
|
||||
```
|
||||
|
||||
1. First
|
||||
2. Second
|
||||
3. Third
|
||||
|
||||
- Item 1
|
||||
- Item 2
|
||||
|
||||
> Quote here
|
||||
|
||||
|
||||
|
||||
| Table | Description |
|
||||
| ----- | ----------- |
|
||||
| Hello | World |
|
||||
````
|
||||
|
||||
### Auto Links
|
||||
|
||||
Internal links use the `next/link` component to allow prefetching and avoid hard-reload.
|
||||
|
||||
External links will get the default `rel="noreferrer noopener" target="_blank"` attributes for security.
|
||||
|
||||
```mdx
|
||||
[My Link](https://github.github.com/gfm)
|
||||
|
||||
This also works: https://github.github.com/gfm.
|
||||
```
|
||||
|
||||
## MDX
|
||||
|
||||
MDX is a superset of Markdown, with support of JSX syntax.
|
||||
It allows you to import components, and use them right in the document, or even export values.
|
||||
|
||||
```mdx
|
||||
import { Component } from './component';
|
||||
|
||||
<Component name="Hello" />
|
||||
```
|
||||
|
||||
see [MDX Syntax](https://mdxjs.com/docs/what-is-mdx/#mdx-syntax) to learn more.
|
||||
|
||||
### Cards
|
||||
|
||||
Useful for adding links, it is included by default.
|
||||
|
||||
```mdx
|
||||
<Cards>
|
||||
<Card
|
||||
href="https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating"
|
||||
title="Fetching, Caching, and Revalidating"
|
||||
>
|
||||
Learn more about caching in Next.js
|
||||
</Card>
|
||||
</Cards>
|
||||
```
|
||||
|
||||
<Cards>
|
||||
<Card
|
||||
href="https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating"
|
||||
title="Fetching, Caching, and Revalidating"
|
||||
>
|
||||
Learn more about caching in Next.js
|
||||
</Card>
|
||||
</Cards>
|
||||
|
||||
#### Icon
|
||||
|
||||
You can specify an icon to cards.
|
||||
|
||||
```mdx
|
||||
import { HomeIcon } from 'lucide-react';
|
||||
|
||||
<Cards>
|
||||
<Card icon={<HomeIcon />} href="/" title="Home">
|
||||
Go back to home
|
||||
</Card>
|
||||
</Cards>
|
||||
```
|
||||
|
||||
<Cards>
|
||||
<Card icon={<HomeIcon />} href="/" title="Go back to home">
|
||||
The home page of Fumadocs.
|
||||
</Card>
|
||||
</Cards>
|
||||
|
||||
#### Without href
|
||||
|
||||
```mdx
|
||||
<Cards>
|
||||
<Card title="Fetching, Caching, and Revalidating">
|
||||
Learn more about `fetch` in Next.js.
|
||||
</Card>
|
||||
</Cards>
|
||||
```
|
||||
|
||||
<Cards>
|
||||
<Card title="Fetching, Caching, and Revalidating">
|
||||
Learn more about `fetch` in Next.js.
|
||||
</Card>
|
||||
</Cards>
|
||||
|
||||
### Callouts
|
||||
|
||||
Useful for adding tips/warnings, it is included by default.
|
||||
|
||||
```mdx
|
||||
<Callout>Hello World</Callout>
|
||||
```
|
||||
|
||||
<Callout>Hello World</Callout>
|
||||
|
||||
#### Title
|
||||
|
||||
Specify a callout title.
|
||||
|
||||
```mdx
|
||||
<Callout title="Title">Hello World</Callout>
|
||||
```
|
||||
|
||||
<Callout title="Title">Hello World</Callout>
|
||||
|
||||
#### Types
|
||||
|
||||
You can specify the type of callout.
|
||||
|
||||
- `info` (default)
|
||||
- `warn`
|
||||
- `error`
|
||||
|
||||
```mdx
|
||||
<Callout title="Title" type="error">
|
||||
Hello World
|
||||
</Callout>
|
||||
```
|
||||
|
||||
<Callout title="Title" type="error">
|
||||
Hello World
|
||||
</Callout>
|
||||
|
||||
### Customise Components
|
||||
|
||||
See [all MDX components and available options](/docs/mdx).
|
||||
|
||||
## Headings
|
||||
|
||||
An anchor is automatically applied to each heading, it sanitizes invalid characters like spaces. (e.g. `Hello World` to `hello-world`)
|
||||
|
||||
```md
|
||||
# Hello `World`
|
||||
```
|
||||
|
||||
### TOC Settings
|
||||
|
||||
The table of contents (TOC) will be generated based on headings, you can also customise the effects of headings:
|
||||
|
||||
```md
|
||||
# Heading [!toc]
|
||||
|
||||
This heading will be hidden from TOC.
|
||||
|
||||
# Another Heading [toc]
|
||||
|
||||
This heading will **only** be visible in TOC, you can use it to add additional TOC items.
|
||||
Like headings rendered in a React component:
|
||||
|
||||
<MyComp />
|
||||
```
|
||||
|
||||
### Custom Anchor
|
||||
|
||||
You can add `[#slug]` to customise heading anchors.
|
||||
|
||||
```md
|
||||
# heading [#my-heading-id]
|
||||
```
|
||||
|
||||
You can also chain it with TOC settings like:
|
||||
|
||||
```md
|
||||
# heading [toc] [#my-heading-id]
|
||||
```
|
||||
|
||||
To link people to a specific heading, add the heading id to hash fragment: `/page#my-heading-id`.
|
||||
|
||||
## Frontmatter
|
||||
|
||||
We support YAML frontmatter. It is a way to specify common information of the document (e.g. title).
|
||||
Place it at the top of document.
|
||||
|
||||
```mdx
|
||||
---
|
||||
title: Hello World
|
||||
---
|
||||
|
||||
## Title
|
||||
```
|
||||
|
||||
See [Page Conventions](/docs/page-conventions#frontmatter) for a list of properties available for frontmatter.
|
||||
|
||||
## Codeblock
|
||||
|
||||
Syntax Highlighting is supported by default using [Rehype Code](/docs/headless/mdx/rehype-code).
|
||||
|
||||
````mdx
|
||||
```js
|
||||
console.log('Hello World');
|
||||
```
|
||||
````
|
||||
|
||||
You can add a title to the codeblock.
|
||||
|
||||
````mdx
|
||||
```js title="My Title"
|
||||
console.log('Hello World');
|
||||
```
|
||||
````
|
||||
|
||||
### Highlight Lines
|
||||
|
||||
You can highlight specific lines by adding `[!code highlight]`.
|
||||
|
||||
````md
|
||||
```tsx
|
||||
<div>Hello World</div> // [\!code highlight]
|
||||
<div>Hello World</div>
|
||||
<div>Goodbye</div>
|
||||
<div>Hello World</div>
|
||||
```
|
||||
````
|
||||
|
||||
### Highlight Words
|
||||
|
||||
You can highlight a specific word by adding `[!code word:<match>]`.
|
||||
|
||||
````md
|
||||
```js
|
||||
// [\!code word:config]
|
||||
const config = {
|
||||
reactStrictMode: true,
|
||||
};
|
||||
```
|
||||
````
|
||||
|
||||
### Diffs
|
||||
|
||||
````mdx
|
||||
```ts
|
||||
console.log('hewwo'); // [\!code --]
|
||||
console.log('hello'); // [\!code ++]
|
||||
```
|
||||
````
|
||||
|
||||
```ts
|
||||
console.log('hewwo'); // [!code --]
|
||||
console.log('hello'); // [!code ++]
|
||||
```
|
||||
|
||||
### Tab Groups
|
||||
|
||||
You can use code blocks with the `<Tab />` component.
|
||||
|
||||
````mdx
|
||||
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
|
||||
|
||||
```ts tab="Tab 1"
|
||||
console.log('A');
|
||||
```
|
||||
|
||||
```ts tab="Tab 2"
|
||||
console.log('B');
|
||||
```
|
||||
````
|
||||
|
||||
> Note that you can add MDX components instead of importing them in MDX files.
|
||||
|
||||
```ts tab="Tab 1"
|
||||
console.log('A');
|
||||
```
|
||||
|
||||
```ts tab="Tab 2"
|
||||
console.log('B');
|
||||
```
|
||||
|
||||
### Using Typescript Twoslash
|
||||
|
||||
Write Typescript codeblocks with hover type information and detected types errors.
|
||||
|
||||
Not enabled by default. See [Twoslash](/docs/twoslash).
|
||||
|
||||
## Images
|
||||
|
||||
All built-in content sources handle images properly.
|
||||
Images are automatically optimized for `next/image`.
|
||||
|
||||
```mdx
|
||||
|
||||
```
|
||||
|
||||
## Optional
|
||||
|
||||
Some optional plugins you can enable.
|
||||
|
||||
### Math Equations
|
||||
|
||||
Write math equations with TeX.
|
||||
|
||||
````md
|
||||
```math
|
||||
f(x) = x * e^{2 pi i \xi x}
|
||||
```
|
||||
````
|
||||
|
||||
```math
|
||||
f(x) = x * e^{2 pi i \xi x}
|
||||
```
|
||||
|
||||
To enable, see [Math Integration](/docs/math).
|
||||
|
||||
### Package Install
|
||||
|
||||
Generate code blocks for installing packages via package managers (JS/Node.js).
|
||||
|
||||
````md
|
||||
```package-install
|
||||
npm i next -D
|
||||
```
|
||||
````
|
||||
|
||||
```package-install
|
||||
npm i next -D
|
||||
```
|
||||
|
||||
To enable, see [Remark Install](/docs/headless/mdx/install).
|
||||
|
||||
### More
|
||||
|
||||
You can see [a list of plugins](/docs/headless/mdx) supported by Fumadocs.
|
||||
254
content/blog/markdown.zh.mdx
Normal file
254
content/blog/markdown.zh.mdx
Normal file
@ -0,0 +1,254 @@
|
||||
---
|
||||
title: Markdown
|
||||
description: 如何撰写文档
|
||||
image: /images/blog/mkdirs-og.png
|
||||
date: 2024-11-25T12:00:00.000Z
|
||||
published: true
|
||||
categories: [news, company]
|
||||
author: mkdirs
|
||||
---
|
||||
|
||||
## 介绍
|
||||
|
||||
Fumadocs 为 MDX（一种标记语言）提供了许多有用的扩展。以下是 Fumadocs UI 默认 MDX 语法的简要介绍。
|
||||
|
||||
> MDX 不是 Fumadocs 唯一支持的格式。实际上，您可以使用任何渲染器，如 `next-mdx-remote` 或 CMS。
|
||||
|
||||
## Markdown
|
||||
|
||||
我们使用 GFM（GitHub 风格的 Markdown），这是 Markdown（CommonMark）的超集。
|
||||
参见 [GFM 规范](https://github.github.com/gfm)。
|
||||
|
||||
````md
|
||||
# Heading
|
||||
|
||||
## Heading
|
||||
|
||||
### Heading
|
||||
|
||||
#### Heading
|
||||
|
||||
Hello World, **Bold**, _Italic_, ~~Hidden~~
|
||||
|
||||
```js
|
||||
console.log('Hello World');
|
||||
```
|
||||
|
||||
1. First
|
||||
2. Second
|
||||
3. Third
|
||||
|
||||
- Item 1
|
||||
- Item 2
|
||||
|
||||
> Quote here
|
||||
|
||||
|
||||
|
||||
| Table | Description |
|
||||
| ----- | ----------- |
|
||||
| Hello | World |
|
||||
````
|
||||
|
||||
### 自动链接
|
||||
|
||||
内部链接使用 `next/link` 组件，允许预取并避免硬重载。
|
||||
|
||||
外部链接将获得默认的 `rel="noreferrer noopener" target="_blank"` 属性以增强安全性。
|
||||
|
||||
```mdx
|
||||
[My Link](https://github.github.com/gfm)
|
||||
|
||||
This also works: https://github.github.com/gfm.
|
||||
```
|
||||
|
||||
## MDX
|
||||
|
||||
MDX 是 Markdown 的超集，支持 JSX 语法。
|
||||
它允许您导入组件，并直接在文档中使用它们，甚至导出值。
|
||||
|
||||
```mdx
|
||||
import { Component } from './component';
|
||||
|
||||
<Component name="Hello" />
|
||||
```
|
||||
|
||||
参见 [MDX 语法](https://mdxjs.com/docs/what-is-mdx/#mdx-syntax) 了解更多信息。
|
||||
|
||||
### 卡片
|
||||
|
||||
对于添加链接很有用，默认包含。
|
||||
|
||||
```mdx
|
||||
<Cards>
|
||||
<Card
|
||||
href="https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating"
|
||||
title="Fetching, Caching, and Revalidating"
|
||||
>
|
||||
Learn more about caching in Next.js
|
||||
</Card>
|
||||
</Cards>
|
||||
```
|
||||
|
||||
<Cards>
|
||||
<Card
|
||||
href="https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating"
|
||||
title="Fetching, Caching, and Revalidating"
|
||||
>
|
||||
Learn more about caching in Next.js
|
||||
</Card>
|
||||
</Cards>
|
||||
|
||||
#### 图标
|
||||
|
||||
您可以为卡片指定图标。
|
||||
|
||||
```mdx
|
||||
import { HomeIcon } from 'lucide-react';
|
||||
|
||||
<Cards>
|
||||
<Card icon={<HomeIcon />} href="/" title="Home">
|
||||
Go back to home
|
||||
</Card>
|
||||
</Cards>
|
||||
```
|
||||
|
||||
<Cards>
|
||||
<Card icon={<HomeIcon />} href="/" title="Go back to home">
|
||||
The home page of Fumadocs.
|
||||
</Card>
|
||||
</Cards>
|
||||
|
||||
#### 无 href
|
||||
|
||||
```mdx
|
||||
<Cards>
|
||||
<Card title="Fetching, Caching, and Revalidating">
|
||||
Learn more about `fetch` in Next.js.
|
||||
</Card>
|
||||
</Cards>
|
||||
```
|
||||
|
||||
<Cards>
|
||||
<Card title="Fetching, Caching, and Revalidating">
|
||||
Learn more about `fetch` in Next.js.
|
||||
</Card>
|
||||
</Cards>
|
||||
|
||||
### 提示框
|
||||
|
||||
对于添加提示/警告很有用，默认包含。
|
||||
|
||||
```mdx
|
||||
<Callout>Hello World</Callout>
|
||||
```
|
||||
|
||||
<Callout>Hello World</Callout>
|
||||
|
||||
#### 标题
|
||||
|
||||
指定提示框标题。
|
||||
|
||||
```mdx
|
||||
<Callout title="Title">Hello World</Callout>
|
||||
```
|
||||
|
||||
<Callout title="Title">Hello World</Callout>
|
||||
|
||||
#### 类型
|
||||
|
||||
您可以指定提示框的类型。
|
||||
|
||||
- `info`（默认）
|
||||
- `warn`
|
||||
- `error`
|
||||
|
||||
```mdx
|
||||
<Callout title="Title" type="error">
|
||||
Hello World
|
||||
</Callout>
|
||||
```
|
||||
|
||||
<Callout title="Title" type="error">
|
||||
Hello World
|
||||
</Callout>
|
||||
|
||||
### 自定义组件
|
||||
|
||||
参见[所有 MDX 组件和可用选项](/docs/mdx)。
|
||||
|
||||
## 标题
|
||||
|
||||
每个标题会自动应用锚点，它会清理空格等无效字符。（例如，`Hello World` 变为 `hello-world`）
|
||||
|
||||
```md
|
||||
# Hello `World`
|
||||
```
|
||||
|
||||
### 目录设置
|
||||
|
||||
目录 (TOC) 将基于标题生成，您还可以自定义标题的效果：
|
||||
|
||||
```md
|
||||
# Heading [!toc]
|
||||
|
||||
This heading will be hidden from TOC.
|
||||
|
||||
# Another Heading [toc]
|
||||
|
||||
This heading will **only** be visible in TOC, you can use it to add additional TOC items.
|
||||
Like headings rendered in a React component:
|
||||
|
||||
<MyComp />
|
||||
```
|
||||
|
||||
### 自定义锚点
|
||||
|
||||
您可以添加 `[#slug]` 来自定义标题锚点。
|
||||
|
||||
```md
|
||||
# heading [#my-heading-id]
|
||||
```
|
||||
|
||||
您也可以将其与目录设置链接起来，例如：
|
||||
|
||||
```md
|
||||
# heading [toc] [#my-heading-id]
|
||||
```
|
||||
|
||||
要将人们链接到特定标题，请将标题 ID 添加到哈希片段：`/page#my-heading-id`。
|
||||
|
||||
## 前言
|
||||
|
||||
我们支持 YAML 前言。这是一种指定文档常见信息（例如标题）的方式。
|
||||
将其放在文档顶部。
|
||||
|
||||
```mdx
|
||||
---
|
||||
title: Hello World
|
||||
---
|
||||
|
||||
## Title
|
||||
```
|
||||
|
||||
有关前言可用属性的列表，请参见[页面约定](/docs/page-conventions#frontmatter)。
|
||||
|
||||
## 代码块
|
||||
|
||||
默认使用 [Rehype Code](/docs/headless/mdx/rehype-code) 支持语法高亮。
|
||||
|
||||
````mdx
|
||||
```js
|
||||
console.log('Hello World');
|
||||
```
|
||||
````
|
||||
|
||||
您可以为代码块添加标题。
|
||||
|
||||
````mdx
|
||||
```js title="My Title"
|
||||
console.log('Hello World');
|
||||
```
|
||||
````
|
||||
|
||||
### 高亮行
|
||||
@ -1,215 +0,0 @@
|
||||
---
|
||||
title: What is Boilerplate Hunt?
|
||||
description: Find the best boilerplates to ship faster. Explore production-ready boilerplates for SaaS, web, and mobile applications.
|
||||
image: /images/blog/boilerplatehunt-og.png
|
||||
date: 2024-11-24T12:00:00.000Z
|
||||
published: true
|
||||
categories: [company, product]
|
||||
author: boilerplatehunt
|
||||
locale: en
|
||||
---
|
||||
|
||||
Until now, trying to style an article, document, or blog post with Tailwind has been a tedious task that required a keen eye for typography and a lot of complex custom CSS.
|
||||
|
||||
By default, Tailwind removes all of the default browser styling from paragraphs, headings, lists and more. This ends up being really useful for building application UIs because you spend less time undoing user-agent styles, but when you _really are_ just trying to style some content that came from a rich-text editor in a CMS or a markdown file, it can be surprising and unintuitive.
|
||||
|
||||
We get lots of complaints about it actually, with people regularly asking us things like:
|
||||
|
||||
> Why is Tailwind removing the default styles on my `h1` elements? How do I disable this? What do you mean I lose all the other base styles too?
|
||||
> We hear you, but we're not convinced that simply disabling our base styles is what you really want. You don't want to have to remove annoying margins every time you use a `p` element in a piece of your dashboard UI. And I doubt you really want your blog posts to use the user-agent styles either — you want them to look _awesome_, not awful.
|
||||
|
||||
The `@tailwindcss/typography` plugin is our attempt to give you what you _actually_ want, without any of the downsides of doing something stupid like disabling our base styles.
|
||||
|
||||
It adds a new `prose` class that you can slap on any block of vanilla HTML content and turn it into a beautiful, well-formatted document:
|
||||
|
||||
```html
|
||||
<article class="prose">
|
||||
<h1>Garlic bread with cheese: What the science tells us</h1>
|
||||
<p>
|
||||
For years parents have espoused the health benefits of eating garlic bread
|
||||
with cheese to their children, with the food earning such an iconic status
|
||||
in our culture that kids will often dress up as warm, cheesy loaf for
|
||||
Halloween.
|
||||
</p>
|
||||
<p>
|
||||
But a recent study shows that the celebrated appetizer may be linked to a
|
||||
series of rabies cases springing up around the country.
|
||||
</p>
|
||||
</article>
|
||||
```
|
||||
|
||||
For more information about how to use the plugin and the features it includes, [read the documentation](https://github.com/tailwindcss/typography/blob/master/README.md).
|
||||
|
||||
---
|
||||
|
||||
## What to expect from here on out
|
||||
|
||||
What follows from here is just a bunch of absolute nonsense I've written to dogfood the plugin itself. It includes every sensible typographic element I could think of, like **bold text**, unordered lists, ordered lists, code blocks, block quotes, _and even italics_.
|
||||
|
||||
It's important to cover all of these use cases for a few reasons:
|
||||
|
||||
1. We want everything to look good out of the box.
|
||||
2. Really just the first reason, that's the whole point of the plugin.
|
||||
3. Here's a third pretend reason though a list with three items looks more realistic than a list with two items.
|
||||
|
||||
Now we're going to try out another header style.
|
||||
|
||||
### Typography should be easy
|
||||
|
||||
So that's a header for you — with any luck if we've done our job correctly that will look pretty reasonable.
|
||||
|
||||
Something a wise person once told me about typography is:
|
||||
|
||||
> Typography is pretty important if you don't want your stuff to look like trash. Make it good then it won't be bad.
|
||||
|
||||
It's probably important that images look okay here by default as well:
|
||||
|
||||
<img
|
||||
src="/images/blog/mksaas-og.png"
|
||||
width="718"
|
||||
height="404"
|
||||
alt="Image"
|
||||
/>
|
||||
|
||||
Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old.
|
||||
|
||||
Now I'm going to show you an example of an unordered list to make sure that looks good, too:
|
||||
|
||||
- So here is the first item in this list.
|
||||
- In this example we're keeping the items short.
|
||||
- Later, we'll use longer, more complex list items.
|
||||
|
||||
And that's the end of this section.
|
||||
|
||||
## What if we stack headings?
|
||||
|
||||
### We should make sure that looks good, too.
|
||||
|
||||
Sometimes you have headings directly underneath each other. In those cases you often have to undo the top margin on the second heading because it usually looks better for the headings to be closer together than a paragraph followed by a heading should be.
|
||||
|
||||
### When a heading comes after a paragraph …
|
||||
|
||||
When a heading comes after a paragraph, we need a bit more space, like I already mentioned above. Now let's see what a more complex list would look like.
|
||||
|
||||
- **I often do this thing where list items have headings.**
|
||||
|
||||
For some reason I think this looks cool which is unfortunate because it's pretty annoying to get the styles right.
|
||||
|
||||
I often have two or three paragraphs in these list items, too, so the hard part is getting the spacing between the paragraphs, list item heading, and separate list items to all make sense. Pretty tough honestly, you could make a strong argument that you just shouldn't write this way.
|
||||
|
||||
- **Since this is a list, I need at least two items.**
|
||||
|
||||
I explained what I'm doing already in the previous list item, but a list wouldn't be a list if it only had one item, and we really want this to look realistic. That's why I've added this second list item so I actually have something to look at when writing the styles.
|
||||
|
||||
- **It's not a bad idea to add a third item either.**
|
||||
|
||||
I think it probably would've been fine to just use two items but three is definitely not worse, and since I seem to be having no trouble making up arbitrary things to type, I might as well include it.
|
||||
|
||||
After this sort of list I usually have a closing statement or paragraph, because it kinda looks weird jumping right to a heading.
|
||||
|
||||
## Code should look okay by default.
|
||||
|
||||
I think most people are going to use [highlight.js](https://highlightjs.org/) or [Prism](https://prismjs.com/) or something if they want to style their code blocks but it wouldn't hurt to make them look _okay_ out of the box, even with no syntax highlighting.
|
||||
|
||||
Here's what a default `tailwind.config.js` file looks like at the time of writing:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
purge: [],
|
||||
theme: {
|
||||
extend: {},
|
||||
},
|
||||
variants: {},
|
||||
plugins: [],
|
||||
};
|
||||
```
|
||||
|
||||
Hopefully that looks good enough to you.
|
||||
|
||||
### What about nested lists?
|
||||
|
||||
Nested lists basically always look bad which is why editors like Medium don't even let you do it, but I guess since some of you goofballs are going to do it we have to carry the burden of at least making it work.
|
||||
|
||||
1. **Nested lists are rarely a good idea.**
|
||||
- You might feel like you are being really "organized" or something but you are just creating a gross shape on the screen that is hard to read.
|
||||
- Nested navigation in UIs is a bad idea too, keep things as flat as possible.
|
||||
- Nesting tons of folders in your source code is also not helpful.
|
||||
2. **Since we need to have more items, here's another one.**
|
||||
- I'm not sure if we'll bother styling more than two levels deep.
|
||||
- Two is already too much, three is guaranteed to be a bad idea.
|
||||
- If you nest four levels deep you belong in prison.
|
||||
3. **Two items isn't really a list, three is good though.**
|
||||
- Again please don't nest lists if you want people to actually read your content.
|
||||
- Nobody wants to look at this.
|
||||
- I'm upset that we even have to bother styling this.
|
||||
|
||||
The most annoying thing about lists in Markdown is that `<li>` elements aren't given a child `<p>` tag unless there are multiple paragraphs in the list item. That means I have to worry about styling that annoying situation too.
|
||||
|
||||
- **For example, here's another nested list.**
|
||||
|
||||
But this time with a second paragraph.
|
||||
|
||||
- These list items won't have `<p>` tags
|
||||
- Because they are only one line each
|
||||
|
||||
- **But in this second top-level list item, they will.**
|
||||
|
||||
This is especially annoying because of the spacing on this paragraph.
|
||||
|
||||
- As you can see here, because I've added a second line, this list item now has a `<p>` tag.
|
||||
|
||||
This is the second line I'm talking about by the way.
|
||||
|
||||
- Finally here's another list item so it's more like a list.
|
||||
|
||||
- A closing list item, but with no nested list, because why not?
|
||||
|
||||
And finally a sentence to close off this section.
|
||||
|
||||
## There are other elements we need to style
|
||||
|
||||
I almost forgot to mention links, like [this link to the Tailwind CSS website](https://tailwindcss.com). We almost made them blue but that's so yesterday, so we went with dark gray, feels edgier.
|
||||
|
||||
We even included table styles, check it out:
|
||||
|
||||
| Wrestler | Origin | Finisher |
|
||||
| ----------------------- | ------------ | ------------------ |
|
||||
| Bret "The Hitman" Hart | Calgary, AB | Sharpshooter |
|
||||
| Stone Cold Steve Austin | Austin, TX | Stone Cold Stunner |
|
||||
| Randy Savage | Sarasota, FL | Elbow Drop |
|
||||
| Vader | Boulder, CO | Vader Bomb |
|
||||
| Razor Ramon | Chuluota, FL | Razor's Edge |
|
||||
|
||||
We also need to make sure inline code looks good, like if I wanted to talk about `<span>` elements or tell you the good news about `@tailwindcss/typography`.
|
||||
|
||||
### Sometimes I even use `code` in headings
|
||||
|
||||
Even though it's probably a bad idea, and historically I've had a hard time making it look good. This _"wrap the code blocks in backticks"_ trick works pretty well though really.
|
||||
|
||||
Another thing I've done in the past is put a `code` tag inside of a link, like if I wanted to tell you about the [`tailwindcss/docs`](https://github.com/tailwindcss/docs) repository. I don't love that there is an underline below the backticks but it is absolutely not worth the madness it would require to avoid it.
|
||||
|
||||
#### We haven't used an `h4` yet
|
||||
|
||||
But now we have. Please don't use `h5` or `h6` in your content, Medium only supports two heading levels for a reason, you animals. I honestly considered using a `before` pseudo-element to scream at you if you use an `h5` or `h6`.
|
||||
|
||||
We don't style them at all out of the box because `h4` elements are already so small that they are the same size as the body copy. What are we supposed to do with an `h5`, make it _smaller_ than the body copy? No thanks.
|
||||
|
||||
### We still need to think about stacked headings though.
|
||||
|
||||
#### Let's make sure we don't screw that up with `h4` elements, either.
|
||||
|
||||
Phew, with any luck we have styled the headings above this text and they look pretty good.
|
||||
|
||||
Let's add a closing paragraph here so things end with a decently sized block of text. I can't explain why I want things to end that way but I have to assume it's because I think things will look weird or unbalanced if there is a heading too close to the end of the document.
|
||||
|
||||
What I've written here is probably long enough, but adding this final sentence can't hurt.
|
||||
|
||||
## GitHub Flavored Markdown
|
||||
|
||||
I've also added support for GitHub Flavored Mardown using `remark-gfm`.
|
||||
|
||||
With `remark-gfm`, we get a few extra features in our markdown. Example: autolink literals.
|
||||
|
||||
A link like www.example.com or https://example.com would automatically be converted into an `a` tag.
|
||||
|
||||
This works for email links too: contact@example.com.
|
||||
@ -1,215 +0,0 @@
|
||||
---
|
||||
title: Boilerplate Hunt 是什么？
|
||||
description: 发现最好的代码模板，更快地构建你的应用。
|
||||
image: /images/blog/boilerplatehunt-og.png
|
||||
date: 2024-11-24T12:00:00.000Z
|
||||
published: true
|
||||
categories: [company, product]
|
||||
author: boilerplatehunt
|
||||
locale: zh
|
||||
---
|
||||
|
||||
到目前为止，尝试使用 Tailwind 来设计文章、文档或博客文章的样式一直是一项繁琐的任务，需要对排版有敏锐的眼光，并且需要大量复杂的自定义 CSS。
|
||||
|
||||
默认情况下，Tailwind 会删除段落、标题、列表等所有默认的浏览器样式。这对于构建应用程序 UI 非常有用，因为您花更少的时间撤销用户代理样式，但是当您真的只是尝试设置来自 CMS 中富文本编辑器或 markdown 文件的内容的样式时，这可能会令人惊讶和不直观。
|
||||
|
||||
我们实际上收到了很多关于它的投诉，人们经常问我们这样的问题：
|
||||
|
||||
> 为什么 Tailwind 删除了我的 `h1` 元素上的默认样式？我如何禁用这个？你说我也会失去所有其他基本样式是什么意思？
|
||||
> 我们听到了您的声音，但我们并不确信简单地禁用我们的基本样式就是您真正想要的。您不希望每次在仪表板 UI 的一部分中使用 `p` 元素时都必须删除烦人的边距。而且我怀疑您真的希望您的博客文章使用用户代理样式——您希望它们看起来很棒，而不是糟糕。
|
||||
|
||||
`@tailwindcss/typography` 插件是我们尝试给您真正想要的东西，而不会有做一些愚蠢的事情（比如禁用我们的基本样式）的任何缺点。
|
||||
|
||||
它添加了一个新的 `prose` 类，您可以将其应用于任何普通 HTML 内容块，并将其转变为一个美丽、格式良好的文档：
|
||||
|
||||
```html
|
||||
<article class="prose">
|
||||
<h1>Garlic bread with cheese: What the science tells us</h1>
|
||||
<p>
|
||||
For years parents have espoused the health benefits of eating garlic bread
|
||||
with cheese to their children, with the food earning such an iconic status
|
||||
in our culture that kids will often dress up as warm, cheesy loaf for
|
||||
Halloween.
|
||||
</p>
|
||||
<p>
|
||||
But a recent study shows that the celebrated appetizer may be linked to a
|
||||
series of rabies cases springing up around the country.
|
||||
</p>
|
||||
</article>
|
||||
```
|
||||
|
||||
有关如何使用该插件及其包含的功能的更多信息，[阅读文档](https://github.com/tailwindcss/typography/blob/master/README.md)。
|
||||
|
||||
---
|
||||
|
||||
## 从现在开始期待什么
|
||||
|
||||
从这里开始的是我写的一堆绝对无意义的内容，用来测试插件本身。它包括我能想到的每一个合理的排版元素，如**粗体文本**、无序列表、有序列表、代码块、块引用，_甚至斜体_。
|
||||
|
||||
涵盖所有这些用例很重要，原因如下：
|
||||
|
||||
1. 我们希望一切开箱即用看起来都很好。
|
||||
2. 实际上只是第一个原因，这是插件的全部意义。
|
||||
3. 这里有第三个假装的原因，尽管一个有三个项目的列表看起来比一个有两个项目的列表更真实。
|
||||
|
||||
现在我们将尝试另一种标题样式。
|
||||
|
||||
### 排版应该很简单
|
||||
|
||||
所以这是给你的一个标题——如果我们做得正确，那应该看起来相当合理。
|
||||
|
||||
一位智者曾经告诉我关于排版的一件事是：
|
||||
|
||||
> 如果你不希望你的东西看起来像垃圾，排版是非常重要的。做好它，那么它就不会糟糕。
|
||||
|
||||
默认情况下，图片在这里看起来也应该不错：
|
||||
|
||||
<img
|
||||
src="/images/blog/mksaas-og.png"
|
||||
width="718"
|
||||
height="404"
|
||||
alt="图片"
|
||||
/>
|
||||
|
||||
与普遍的看法相反，Lorem Ipsum 并不是简单的随机文本。它起源于公元前 45 年的一段古典拉丁文学，使其有超过 2000 年的历史。
|
||||
|
||||
现在我将向您展示一个无序列表的例子，以确保它看起来也不错：
|
||||
|
||||
- 所以这是这个列表中的第一项。
|
||||
- 在这个例子中，我们保持项目简短。
|
||||
- 稍后，我们将使用更长、更复杂的列表项。
|
||||
|
||||
这就是本节的结尾。
|
||||
|
||||
## 如果我们堆叠标题怎么办？
|
||||
|
||||
### 我们也应该确保这看起来不错。
|
||||
|
||||
有时候你有直接堆叠在一起的标题。在这些情况下，你通常必须取消第二个标题上的顶部边距，因为标题彼此靠得更近通常看起来比段落后面跟着标题要好。
|
||||
|
||||
### 当标题在段落之后出现时……
|
||||
|
||||
当标题在段落之后出现时，我们需要更多的空间，就像我上面已经提到的那样。现在让我们看看一个更复杂的列表会是什么样子。
|
||||
|
||||
- **我经常做这种事，列表项有标题。**
|
||||
|
||||
由于某种原因，我认为这看起来很酷，这很不幸，因为要让样式正确是相当烦人的。
|
||||
|
||||
我在这些列表项中通常也有两到三个段落，所以困难的部分是让段落之间的间距、列表项标题和单独的列表项都有意义。老实说，这很困难，你可以提出一个强有力的论点，认为你根本不应该这样写。
|
||||
|
||||
- **由于这是一个列表，我至少需要两个项目。**
|
||||
|
||||
我已经在前面的列表项中解释了我在做什么，但是如果一个列表只有一个项目，那就不是一个列表，我们真的希望这看起来真实。这就是为什么我添加了这第二个列表项，所以我在写样式时实际上有东西可以看。
|
||||
|
||||
- **添加第三项也不是一个坏主意。**
|
||||
|
||||
我认为只使用两个项目可能已经足够了，但三个肯定不会更糟，而且由于我似乎在编造任意的东西时没有遇到麻烦，我不妨包括它。
|
||||
|
||||
在这种列表之后，我通常会有一个结束语或段落，因为直接跳到标题看起来有点奇怪。
|
||||
|
||||
## 代码默认应该看起来不错。
|
||||
|
||||
我认为大多数人如果想要设置他们的代码块的样式，会使用 [highlight.js](https://highlightjs.org/) 或 [Prism](https://prismjs.com/) 或其他东西，但是让它们开箱即用看起来_还不错_，即使没有语法高亮，也不会有害。
|
||||
|
||||
以下是撰写本文时默认的 `tailwind.config.js` 文件的样子：
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
purge: [],
|
||||
theme: {
|
||||
extend: {},
|
||||
},
|
||||
variants: {},
|
||||
plugins: [],
|
||||
};
|
||||
```
|
||||
|
||||
希望这对你来说看起来足够好。
|
||||
|
||||
### 嵌套列表怎么办？
|
||||
|
||||
嵌套列表基本上总是看起来很糟糕，这就是为什么像 Medium 这样的编辑器甚至不让你这样做，但我猜既然你们中的一些傻瓜要这样做，我们至少要承担让它工作的负担。
|
||||
|
||||
1. **嵌套列表很少是一个好主意。**
|
||||
- 你可能觉得你真的很"有组织"或者什么的，但你只是在屏幕上创建一个难以阅读的粗糙形状。
|
||||
- UI 中的嵌套导航也是一个坏主意，尽可能保持扁平。
|
||||
- 在源代码中嵌套大量文件夹也没有帮助。
|
||||
2. **既然我们需要有更多的项目，这里有另一个。**
|
||||
- 我不确定我们是否会费心设置超过两级深度的样式。
|
||||
- 两级已经太多了，三级肯定是一个坏主意。
|
||||
- 如果你嵌套四级深度，你应该进监狱。
|
||||
3. **两个项目并不是真正的列表，三个项目就好了。**
|
||||
- 再次请不要嵌套列表，如果你希望人们真正阅读你的内容。
|
||||
- 没有人想看这个。
|
||||
- 我很不高兴我们甚至必须费心设置这个样式。
|
||||
|
||||
Markdown 中列表最烦人的事情是，除非列表项中有多个段落，否则 `<li>` 元素不会被赋予子 `<p>` 标签。这意味着我也必须担心设置那种烦人情况的样式。
|
||||
|
||||
- **例如，这里是另一个嵌套列表。**
|
||||
|
||||
但这次有第二段。
|
||||
|
||||
- 这些列表项不会有 `<p>` 标签
|
||||
- 因为它们每个只有一行
|
||||
|
||||
- **但在这第二个顶级列表项中，它们会有。**
|
||||
|
||||
这特别烦人，因为这段话的间距。
|
||||
|
||||
- 正如你在这里看到的，因为我添加了第二行，这个列表项现在有一个 `<p>` 标签。
|
||||
|
||||
顺便说一下，这是我说的第二行。
|
||||
|
||||
- 最后这里有另一个列表项，所以它更像一个列表。
|
||||
|
||||
- 一个结束列表项，但没有嵌套列表，为什么不呢？
|
||||
|
||||
最后一句话结束这一节。
|
||||
|
||||
## 还有其他我们需要设置样式的元素
|
||||
|
||||
我几乎忘了提到链接，比如[这个链接到 Tailwind CSS 网站](https://tailwindcss.com)。我们几乎把它们变成蓝色，但那是昨天的事了，所以我们选择了深灰色，感觉更前卫。
|
||||
|
||||
我们甚至包括了表格样式，看看：
|
||||
|
||||
| 摔跤手 | 出生地 | 终结技 |
|
||||
| ----------------------- | ------------- | ------------------- |
|
||||
| Bret "The Hitman" Hart | Calgary, AB | Sharpshooter |
|
||||
| Stone Cold Steve Austin | Austin, TX | Stone Cold Stunner |
|
||||
| Randy Savage | Sarasota, FL | Elbow Drop |
|
||||
| Vader | Boulder, CO | Vader Bomb |
|
||||
| Razor Ramon | Chuluota, FL | Razor's Edge |
|
||||
|
||||
我们还需要确保内联代码看起来不错，比如如果我想谈论 `<span>` 元素或者告诉你关于 `@tailwindcss/typography` 的好消息。
|
||||
|
||||
### 有时我甚至在标题中使用 `code`
|
||||
|
||||
尽管这可能是一个坏主意，而且历史上我一直很难让它看起来不错。不过这个_"将代码块包裹在反引号中"_的技巧效果相当不错。
|
||||
|
||||
我过去做过的另一件事是在链接中放置一个 `code` 标签，比如如果我想告诉你关于 [`tailwindcss/docs`](https://github.com/tailwindcss/docs) 仓库的事情。我不喜欢反引号下面有下划线，但为了避免它而导致的疯狂绝对不值得。
|
||||
|
||||
#### 我们还没有使用 `h4`
|
||||
|
||||
但现在我们有了。请不要在你的内容中使用 `h5` 或 `h6`，Medium 只支持两个标题级别是有原因的，你们这些动物。我老实说考虑过使用 `before` 伪元素，如果你使用 `h5` 或 `h6` 就对你大喊大叫。
|
||||
|
||||
我们根本不会为它们设置样式，因为 `h4` 元素已经很小，与正文大小相同。我们应该怎么处理 `h5`，让它比正文更_小_？不，谢谢。
|
||||
|
||||
### 不过我们仍然需要考虑堆叠的标题。
|
||||
|
||||
#### 让我们确保我们也不会用 `h4` 元素搞砸这个。
|
||||
|
||||
呼，运气好的话，我们已经设置了上面这段文字的标题样式，它们看起来相当不错。
|
||||
|
||||
让我们在这里添加一个结束段落，这样事情就会以一个相当大小的文本块结束。我无法解释为什么我希望事情以这种方式结束，但我必须假设这是因为我认为如果文档末尾太靠近标题，事情会看起来奇怪或不平衡。
|
||||
|
||||
我在这里写的可能已经足够长了，但添加这最后一句话不会有害。
|
||||
|
||||
## GitHub 风格的 Markdown
|
||||
|
||||
我还添加了对使用 `remark-gfm` 的 GitHub 风格 Markdown 的支持。
|
||||
|
||||
使用 `remark-gfm`，我们在 markdown 中获得了一些额外的功能。例如：自动链接文字。
|
||||
|
||||
像 www.example.com 或 https://example.com 这样的链接会自动转换为 `a` 标签。
|
||||
|
||||
这对电子邮件链接也有效：contact@example.com。
|
||||
@ -1,215 +0,0 @@
|
||||
---
|
||||
title: What is Coupon?
|
||||
description: Find the best coupons for your favorite products and save money.
|
||||
image: /images/blog/coupon-og.png
|
||||
date: 2024-11-16T12:00:00.000Z
|
||||
published: true
|
||||
categories: [news, product]
|
||||
author: coupon
|
||||
locale: en
|
||||
---
|
||||
|
||||
Until now, trying to style an article, document, or blog post with Tailwind has been a tedious task that required a keen eye for typography and a lot of complex custom CSS.
|
||||
|
||||
By default, Tailwind removes all of the default browser styling from paragraphs, headings, lists and more. This ends up being really useful for building application UIs because you spend less time undoing user-agent styles, but when you _really are_ just trying to style some content that came from a rich-text editor in a CMS or a markdown file, it can be surprising and unintuitive.
|
||||
|
||||
We get lots of complaints about it actually, with people regularly asking us things like:
|
||||
|
||||
> Why is Tailwind removing the default styles on my `h1` elements? How do I disable this? What do you mean I lose all the other base styles too?
|
||||
> We hear you, but we're not convinced that simply disabling our base styles is what you really want. You don't want to have to remove annoying margins every time you use a `p` element in a piece of your dashboard UI. And I doubt you really want your blog posts to use the user-agent styles either — you want them to look _awesome_, not awful.
|
||||
|
||||
The `@tailwindcss/typography` plugin is our attempt to give you what you _actually_ want, without any of the downsides of doing something stupid like disabling our base styles.
|
||||
|
||||
It adds a new `prose` class that you can slap on any block of vanilla HTML content and turn it into a beautiful, well-formatted document:
|
||||
|
||||
```html
|
||||
<article class="prose">
|
||||
<h1>Garlic bread with cheese: What the science tells us</h1>
|
||||
<p>
|
||||
For years parents have espoused the health benefits of eating garlic bread
|
||||
with cheese to their children, with the food earning such an iconic status
|
||||
in our culture that kids will often dress up as warm, cheesy loaf for
|
||||
Halloween.
|
||||
</p>
|
||||
<p>
|
||||
But a recent study shows that the celebrated appetizer may be linked to a
|
||||
series of rabies cases springing up around the country.
|
||||
</p>
|
||||
</article>
|
||||
```
|
||||
|
||||
For more information about how to use the plugin and the features it includes, [read the documentation](https://github.com/tailwindcss/typography/blob/master/README.md).
|
||||
|
||||
---
|
||||
|
||||
## What to expect from here on out
|
||||
|
||||
What follows from here is just a bunch of absolute nonsense I've written to dogfood the plugin itself. It includes every sensible typographic element I could think of, like **bold text**, unordered lists, ordered lists, code blocks, block quotes, _and even italics_.
|
||||
|
||||
It's important to cover all of these use cases for a few reasons:
|
||||
|
||||
1. We want everything to look good out of the box.
|
||||
2. Really just the first reason, that's the whole point of the plugin.
|
||||
3. Here's a third pretend reason though a list with three items looks more realistic than a list with two items.
|
||||
|
||||
Now we're going to try out another header style.
|
||||
|
||||
### Typography should be easy
|
||||
|
||||
So that's a header for you — with any luck if we've done our job correctly that will look pretty reasonable.
|
||||
|
||||
Something a wise person once told me about typography is:
|
||||
|
||||
> Typography is pretty important if you don't want your stuff to look like trash. Make it good then it won't be bad.
|
||||
|
||||
It's probably important that images look okay here by default as well:
|
||||
|
||||
<img
|
||||
src="/images/blog/mksaas-og.png"
|
||||
width="718"
|
||||
height="404"
|
||||
alt="Image"
|
||||
/>
|
||||
|
||||
Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old.
|
||||
|
||||
Now I'm going to show you an example of an unordered list to make sure that looks good, too:
|
||||
|
||||
- So here is the first item in this list.
|
||||
- In this example we're keeping the items short.
|
||||
- Later, we'll use longer, more complex list items.
|
||||
|
||||
And that's the end of this section.
|
||||
|
||||
## What if we stack headings?
|
||||
|
||||
### We should make sure that looks good, too.
|
||||
|
||||
Sometimes you have headings directly underneath each other. In those cases you often have to undo the top margin on the second heading because it usually looks better for the headings to be closer together than a paragraph followed by a heading should be.
|
||||
|
||||
### When a heading comes after a paragraph …
|
||||
|
||||
When a heading comes after a paragraph, we need a bit more space, like I already mentioned above. Now let's see what a more complex list would look like.
|
||||
|
||||
- **I often do this thing where list items have headings.**
|
||||
|
||||
For some reason I think this looks cool which is unfortunate because it's pretty annoying to get the styles right.
|
||||
|
||||
I often have two or three paragraphs in these list items, too, so the hard part is getting the spacing between the paragraphs, list item heading, and separate list items to all make sense. Pretty tough honestly, you could make a strong argument that you just shouldn't write this way.
|
||||
|
||||
- **Since this is a list, I need at least two items.**
|
||||
|
||||
I explained what I'm doing already in the previous list item, but a list wouldn't be a list if it only had one item, and we really want this to look realistic. That's why I've added this second list item so I actually have something to look at when writing the styles.
|
||||
|
||||
- **It's not a bad idea to add a third item either.**
|
||||
|
||||
I think it probably would've been fine to just use two items but three is definitely not worse, and since I seem to be having no trouble making up arbitrary things to type, I might as well include it.
|
||||
|
||||
After this sort of list I usually have a closing statement or paragraph, because it kinda looks weird jumping right to a heading.
|
||||
|
||||
## Code should look okay by default.
|
||||
|
||||
I think most people are going to use [highlight.js](https://highlightjs.org/) or [Prism](https://prismjs.com/) or something if they want to style their code blocks but it wouldn't hurt to make them look _okay_ out of the box, even with no syntax highlighting.
|
||||
|
||||
Here's what a default `tailwind.config.js` file looks like at the time of writing:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
purge: [],
|
||||
theme: {
|
||||
extend: {},
|
||||
},
|
||||
variants: {},
|
||||
plugins: [],
|
||||
};
|
||||
```
|
||||
|
||||
Hopefully that looks good enough to you.
|
||||
|
||||
### What about nested lists?
|
||||
|
||||
Nested lists basically always look bad which is why editors like Medium don't even let you do it, but I guess since some of you goofballs are going to do it we have to carry the burden of at least making it work.
|
||||
|
||||
1. **Nested lists are rarely a good idea.**
|
||||
- You might feel like you are being really "organized" or something but you are just creating a gross shape on the screen that is hard to read.
|
||||
- Nested navigation in UIs is a bad idea too, keep things as flat as possible.
|
||||
- Nesting tons of folders in your source code is also not helpful.
|
||||
2. **Since we need to have more items, here's another one.**
|
||||
- I'm not sure if we'll bother styling more than two levels deep.
|
||||
- Two is already too much, three is guaranteed to be a bad idea.
|
||||
- If you nest four levels deep you belong in prison.
|
||||
3. **Two items isn't really a list, three is good though.**
|
||||
- Again please don't nest lists if you want people to actually read your content.
|
||||
- Nobody wants to look at this.
|
||||
- I'm upset that we even have to bother styling this.
|
||||
|
||||
The most annoying thing about lists in Markdown is that `<li>` elements aren't given a child `<p>` tag unless there are multiple paragraphs in the list item. That means I have to worry about styling that annoying situation too.
|
||||
|
||||
- **For example, here's another nested list.**
|
||||
|
||||
But this time with a second paragraph.
|
||||
|
||||
- These list items won't have `<p>` tags
|
||||
- Because they are only one line each
|
||||
|
||||
- **But in this second top-level list item, they will.**
|
||||
|
||||
This is especially annoying because of the spacing on this paragraph.
|
||||
|
||||
- As you can see here, because I've added a second line, this list item now has a `<p>` tag.
|
||||
|
||||
This is the second line I'm talking about by the way.
|
||||
|
||||
- Finally here's another list item so it's more like a list.
|
||||
|
||||
- A closing list item, but with no nested list, because why not?
|
||||
|
||||
And finally a sentence to close off this section.
|
||||
|
||||
## There are other elements we need to style
|
||||
|
||||
I almost forgot to mention links, like [this link to the Tailwind CSS website](https://tailwindcss.com). We almost made them blue but that's so yesterday, so we went with dark gray, feels edgier.
|
||||
|
||||
We even included table styles, check it out:
|
||||
|
||||
| Wrestler | Origin | Finisher |
|
||||
| ----------------------- | ------------ | ------------------ |
|
||||
| Bret "The Hitman" Hart | Calgary, AB | Sharpshooter |
|
||||
| Stone Cold Steve Austin | Austin, TX | Stone Cold Stunner |
|
||||
| Randy Savage | Sarasota, FL | Elbow Drop |
|
||||
| Vader | Boulder, CO | Vader Bomb |
|
||||
| Razor Ramon | Chuluota, FL | Razor's Edge |
|
||||
|
||||
We also need to make sure inline code looks good, like if I wanted to talk about `<span>` elements or tell you the good news about `@tailwindcss/typography`.
|
||||
|
||||
### Sometimes I even use `code` in headings
|
||||
|
||||
Even though it's probably a bad idea, and historically I've had a hard time making it look good. This _"wrap the code blocks in backticks"_ trick works pretty well though really.
|
||||
|
||||
Another thing I've done in the past is put a `code` tag inside of a link, like if I wanted to tell you about the [`tailwindcss/docs`](https://github.com/tailwindcss/docs) repository. I don't love that there is an underline below the backticks but it is absolutely not worth the madness it would require to avoid it.
|
||||
|
||||
#### We haven't used an `h4` yet
|
||||
|
||||
But now we have. Please don't use `h5` or `h6` in your content, Medium only supports two heading levels for a reason, you animals. I honestly considered using a `before` pseudo-element to scream at you if you use an `h5` or `h6`.
|
||||
|
||||
We don't style them at all out of the box because `h4` elements are already so small that they are the same size as the body copy. What are we supposed to do with an `h5`, make it _smaller_ than the body copy? No thanks.
|
||||
|
||||
### We still need to think about stacked headings though.
|
||||
|
||||
#### Let's make sure we don't screw that up with `h4` elements, either.
|
||||
|
||||
Phew, with any luck we have styled the headings above this text and they look pretty good.
|
||||
|
||||
Let's add a closing paragraph here so things end with a decently sized block of text. I can't explain why I want things to end that way but I have to assume it's because I think things will look weird or unbalanced if there is a heading too close to the end of the document.
|
||||
|
||||
What I've written here is probably long enough, but adding this final sentence can't hurt.
|
||||
|
||||
## GitHub Flavored Markdown
|
||||
|
||||
I've also added support for GitHub Flavored Mardown using `remark-gfm`.
|
||||
|
||||
With `remark-gfm`, we get a few extra features in our markdown. Example: autolink literals.
|
||||
|
||||
A link like www.example.com or https://example.com would automatically be converted into an `a` tag.
|
||||
|
||||
This works for email links too: contact@example.com.
|
||||
@ -1,215 +0,0 @@
|
||||
---
|
||||
title: Coupon 是什么？
|
||||
description: 发现最好的优惠券，节省你的钱。
|
||||
image: /images/blog/coupon-og.png
|
||||
date: 2024-11-16T12:00:00.000Z
|
||||
published: true
|
||||
categories: [news, product]
|
||||
author: coupon
|
||||
locale: zh
|
||||
---
|
||||
|
||||
到目前为止，尝试使用 Tailwind 来设计文章、文档或博客文章的样式一直是一项繁琐的任务，需要对排版有敏锐的眼光，并且需要大量复杂的自定义 CSS。
|
||||
|
||||
默认情况下，Tailwind 会删除段落、标题、列表等所有默认的浏览器样式。这对于构建应用程序 UI 非常有用，因为您花更少的时间撤销用户代理样式，但是当您真的只是尝试设置来自 CMS 中富文本编辑器或 markdown 文件的内容的样式时，这可能会令人惊讶和不直观。
|
||||
|
||||
我们实际上收到了很多关于它的投诉，人们经常问我们这样的问题：
|
||||
|
||||
> 为什么 Tailwind 删除了我的 `h1` 元素上的默认样式？我如何禁用这个？你说我也会失去所有其他基本样式是什么意思？
|
||||
> 我们听到了您的声音，但我们并不确信简单地禁用我们的基本样式就是您真正想要的。您不希望每次在仪表板 UI 的一部分中使用 `p` 元素时都必须删除烦人的边距。而且我怀疑您真的希望您的博客文章使用用户代理样式——您希望它们看起来很棒，而不是糟糕。
|
||||
|
||||
`@tailwindcss/typography` 插件是我们尝试给您真正想要的东西，而不会有做一些愚蠢的事情（比如禁用我们的基本样式）的任何缺点。
|
||||
|
||||
它添加了一个新的 `prose` 类，您可以将其应用于任何普通 HTML 内容块，并将其转变为一个美丽、格式良好的文档：
|
||||
|
||||
```html
|
||||
<article class="prose">
|
||||
<h1>Garlic bread with cheese: What the science tells us</h1>
|
||||
<p>
|
||||
For years parents have espoused the health benefits of eating garlic bread
|
||||
with cheese to their children, with the food earning such an iconic status
|
||||
in our culture that kids will often dress up as warm, cheesy loaf for
|
||||
Halloween.
|
||||
</p>
|
||||
<p>
|
||||
But a recent study shows that the celebrated appetizer may be linked to a
|
||||
series of rabies cases springing up around the country.
|
||||
</p>
|
||||
</article>
|
||||
```
|
||||
|
||||
有关如何使用该插件及其包含的功能的更多信息，[阅读文档](https://github.com/tailwindcss/typography/blob/master/README.md)。
|
||||
|
||||
---
|
||||
|
||||
## 从现在开始期待什么
|
||||
|
||||
从这里开始的是我写的一堆绝对无意义的内容，用来测试插件本身。它包括我能想到的每一个合理的排版元素，如**粗体文本**、无序列表、有序列表、代码块、块引用，_甚至斜体_。
|
||||
|
||||
涵盖所有这些用例很重要，原因如下：
|
||||
|
||||
1. 我们希望一切开箱即用看起来都很好。
|
||||
2. 实际上只是第一个原因，这是插件的全部意义。
|
||||
3. 这里有第三个假装的原因，尽管一个有三个项目的列表看起来比一个有两个项目的列表更真实。
|
||||
|
||||
现在我们将尝试另一种标题样式。
|
||||
|
||||
### 排版应该很简单
|
||||
|
||||
所以这是给你的一个标题——如果我们做得正确，那应该看起来相当合理。
|
||||
|
||||
一位智者曾经告诉我关于排版的一件事是：
|
||||
|
||||
> 如果你不希望你的东西看起来像垃圾，排版是非常重要的。做好它，那么它就不会糟糕。
|
||||
|
||||
默认情况下，图片在这里看起来也应该不错：
|
||||
|
||||
<img
|
||||
src="/images/blog/mksaas-og.png"
|
||||
width="718"
|
||||
height="404"
|
||||
alt="图片"
|
||||
/>
|
||||
|
||||
与普遍的看法相反，Lorem Ipsum 并不是简单的随机文本。它起源于公元前 45 年的一段古典拉丁文学，使其有超过 2000 年的历史。
|
||||
|
||||
现在我将向您展示一个无序列表的例子，以确保它看起来也不错：
|
||||
|
||||
- 所以这是这个列表中的第一项。
|
||||
- 在这个例子中，我们保持项目简短。
|
||||
- 稍后，我们将使用更长、更复杂的列表项。
|
||||
|
||||
这就是本节的结尾。
|
||||
|
||||
## 如果我们堆叠标题怎么办？
|
||||
|
||||
### 我们也应该确保这看起来不错。
|
||||
|
||||
有时候你有直接堆叠在一起的标题。在这些情况下，你通常必须取消第二个标题上的顶部边距，因为标题彼此靠得更近通常看起来比段落后面跟着标题要好。
|
||||
|
||||
### 当标题在段落之后出现时……
|
||||
|
||||
当标题在段落之后出现时，我们需要更多的空间，就像我上面已经提到的那样。现在让我们看看一个更复杂的列表会是什么样子。
|
||||
|
||||
- **我经常做这种事，列表项有标题。**
|
||||
|
||||
由于某种原因，我认为这看起来很酷，这很不幸，因为要让样式正确是相当烦人的。
|
||||
|
||||
我在这些列表项中通常也有两到三个段落，所以困难的部分是让段落之间的间距、列表项标题和单独的列表项都有意义。老实说，这很困难，你可以提出一个强有力的论点，认为你根本不应该这样写。
|
||||
|
||||
- **由于这是一个列表，我至少需要两个项目。**
|
||||
|
||||
我已经在前面的列表项中解释了我在做什么，但是如果一个列表只有一个项目，那就不是一个列表，我们真的希望这看起来真实。这就是为什么我添加了这第二个列表项，所以我在写样式时实际上有东西可以看。
|
||||
|
||||
- **添加第三项也不是一个坏主意。**
|
||||
|
||||
我认为只使用两个项目可能已经足够了，但三个肯定不会更糟，而且由于我似乎在编造任意的东西时没有遇到麻烦，我不妨包括它。
|
||||
|
||||
在这种列表之后，我通常会有一个结束语或段落，因为直接跳到标题看起来有点奇怪。
|
||||
|
||||
## 代码默认应该看起来不错。
|
||||
|
||||
我认为大多数人如果想要设置他们的代码块的样式，会使用 [highlight.js](https://highlightjs.org/) 或 [Prism](https://prismjs.com/) 或其他东西，但是让它们开箱即用看起来_还不错_，即使没有语法高亮，也不会有害。
|
||||
|
||||
以下是撰写本文时默认的 `tailwind.config.js` 文件的样子：
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
purge: [],
|
||||
theme: {
|
||||
extend: {},
|
||||
},
|
||||
variants: {},
|
||||
plugins: [],
|
||||
};
|
||||
```
|
||||
|
||||
希望这对你来说看起来足够好。
|
||||
|
||||
### 嵌套列表怎么办？
|
||||
|
||||
嵌套列表基本上总是看起来很糟糕，这就是为什么像 Medium 这样的编辑器甚至不让你这样做，但我猜既然你们中的一些傻瓜要这样做，我们至少要承担让它工作的负担。
|
||||
|
||||
1. **嵌套列表很少是一个好主意。**
|
||||
- 你可能觉得你真的很"有组织"或者什么的，但你只是在屏幕上创建一个难以阅读的粗糙形状。
|
||||
- UI 中的嵌套导航也是一个坏主意，尽可能保持扁平。
|
||||
- 在源代码中嵌套大量文件夹也没有帮助。
|
||||
2. **既然我们需要有更多的项目，这里有另一个。**
|
||||
- 我不确定我们是否会费心设置超过两级深度的样式。
|
||||
- 两级已经太多了，三级肯定是一个坏主意。
|
||||
- 如果你嵌套四级深度，你应该进监狱。
|
||||
3. **两个项目并不是真正的列表，三个项目就好了。**
|
||||
- 再次请不要嵌套列表，如果你希望人们真正阅读你的内容。
|
||||
- 没有人想看这个。
|
||||
- 我很不高兴我们甚至必须费心设置这个样式。
|
||||
|
||||
Markdown 中列表最烦人的事情是，除非列表项中有多个段落，否则 `<li>` 元素不会被赋予子 `<p>` 标签。这意味着我也必须担心设置那种烦人情况的样式。
|
||||
|
||||
- **例如，这里是另一个嵌套列表。**
|
||||
|
||||
但这次有第二段。
|
||||
|
||||
- 这些列表项不会有 `<p>` 标签
|
||||
- 因为它们每个只有一行
|
||||
|
||||
- **但在这第二个顶级列表项中，它们会有。**
|
||||
|
||||
这特别烦人，因为这段话的间距。
|
||||
|
||||
- 正如你在这里看到的，因为我添加了第二行，这个列表项现在有一个 `<p>` 标签。
|
||||
|
||||
顺便说一下，这是我说的第二行。
|
||||
|
||||
- 最后这里有另一个列表项，所以它更像一个列表。
|
||||
|
||||
- 一个结束列表项，但没有嵌套列表，为什么不呢？
|
||||
|
||||
最后一句话结束这一节。
|
||||
|
||||
## 还有其他我们需要设置样式的元素
|
||||
|
||||
我几乎忘了提到链接，比如[这个链接到 Tailwind CSS 网站](https://tailwindcss.com)。我们几乎把它们变成蓝色，但那是昨天的事了，所以我们选择了深灰色，感觉更前卫。
|
||||
|
||||
我们甚至包括了表格样式，看看：
|
||||
|
||||
| 摔跤手 | 出生地 | 终结技 |
|
||||
| ----------------------- | ------------- | ------------------- |
|
||||
| Bret "The Hitman" Hart | Calgary, AB | Sharpshooter |
|
||||
| Stone Cold Steve Austin | Austin, TX | Stone Cold Stunner |
|
||||
| Randy Savage | Sarasota, FL | Elbow Drop |
|
||||
| Vader | Boulder, CO | Vader Bomb |
|
||||
| Razor Ramon | Chuluota, FL | Razor's Edge |
|
||||
|
||||
我们还需要确保内联代码看起来不错，比如如果我想谈论 `<span>` 元素或者告诉你关于 `@tailwindcss/typography` 的好消息。
|
||||
|
||||
### 有时我甚至在标题中使用 `code`
|
||||
|
||||
尽管这可能是一个坏主意，而且历史上我一直很难让它看起来不错。不过这个_"将代码块包裹在反引号中"_的技巧效果相当不错。
|
||||
|
||||
我过去做过的另一件事是在链接中放置一个 `code` 标签，比如如果我想告诉你关于 [`tailwindcss/docs`](https://github.com/tailwindcss/docs) 仓库的事情。我不喜欢反引号下面有下划线，但为了避免它而导致的疯狂绝对不值得。
|
||||
|
||||
#### 我们还没有使用 `h4`
|
||||
|
||||
但现在我们有了。请不要在你的内容中使用 `h5` 或 `h6`，Medium 只支持两个标题级别是有原因的，你们这些动物。我老实说考虑过使用 `before` 伪元素，如果你使用 `h5` 或 `h6` 就对你大喊大叫。
|
||||
|
||||
我们根本不会为它们设置样式，因为 `h4` 元素已经很小，与正文大小相同。我们应该怎么处理 `h5`，让它比正文更_小_？不，谢谢。
|
||||
|
||||
### 不过我们仍然需要考虑堆叠的标题。
|
||||
|
||||
#### 让我们确保我们也不会用 `h4` 元素搞砸这个。
|
||||
|
||||
呼，运气好的话，我们已经设置了上面这段文字的标题样式，它们看起来相当不错。
|
||||
|
||||
让我们在这里添加一个结束段落，这样事情就会以一个相当大小的文本块结束。我无法解释为什么我希望事情以这种方式结束，但我必须假设这是因为我认为如果文档末尾太靠近标题，事情会看起来奇怪或不平衡。
|
||||
|
||||
我在这里写的可能已经足够长了，但添加这最后一句话不会有害。
|
||||
|
||||
## GitHub 风格的 Markdown
|
||||
|
||||
我还添加了对使用 `remark-gfm` 的 GitHub 风格 Markdown 的支持。
|
||||
|
||||
使用 `remark-gfm`，我们在 markdown 中获得了一些额外的功能。例如：自动链接文字。
|
||||
|
||||
像 www.example.com 或 https://example.com 这样的链接会自动转换为 `a` 标签。
|
||||
|
||||
这对电子邮件链接也有效：contact@example.com。
|
||||
62
content/blog/what-is-fumadocs.mdx
Normal file
62
content/blog/what-is-fumadocs.mdx
Normal file
@ -0,0 +1,62 @@
|
||||
---
|
||||
title: What is Fumadocs
|
||||
description: Introducing Fumadocs, a docs framework that you can break.
|
||||
image: /images/blog/boilerplatehunt-og.png
|
||||
date: 2024-11-24T12:00:00.000Z
|
||||
published: true
|
||||
categories: [company, product]
|
||||
author: mksaas
|
||||
---
|
||||
|
||||
Fumadocs was created because I wanted a more customisable experience for building docs, to be a docs framework that is not opinionated, **a "framework" that you can break**.
|
||||
|
||||
## Philosophy
|
||||
|
||||
**Less Abstraction:** Fumadocs expects you to write code and cooperate with the rest of your software.
|
||||
While most frameworks are configured with a configuration file, they usually lack flexibility when you hope to tune its details.
|
||||
You can’t control how they render the page nor the internal logic. Fumadocs shows you how the app works, instead of a single configuration file.
|
||||
|
||||
**Next.js Fundamentals:** It gives you the utilities and a good-looking UI.
|
||||
You are still using features of Next.js App Router, like **Static Site Generation**. There is nothing new for Next.js developers, so you can use it with confidence.
|
||||
|
||||
**Opinionated on UI:** The only thing Fumadocs UI (the default theme) offers is **User Interface**. The UI is opinionated for bringing better mobile responsiveness and user experience.
|
||||
Instead, we use a much more flexible approach inspired by Shadcn UI — [Fumadocs CLI](/docs/cli), so we can iterate our design quick, and welcome for more feedback about the UI.
|
||||
|
||||
## Why Fumadocs
|
||||
|
||||
Fumadocs is designed with flexibility in mind.
|
||||
|
||||
You can use `fumadocs-core` as a headless UI library and bring your own styles.
|
||||
Fumadocs MDX is also a useful library to handle MDX content in Next.js. It also includes:
|
||||
|
||||
- Many built-in components.
|
||||
- Typescript Twoslash, OpenAPI, and Math (KaTeX) integrations.
|
||||
- Fast and optimized by default, natively built on App Router.
|
||||
- Tight integration with Next.js, you can add it to an existing Next.js project easily.
|
||||
|
||||
You can read [Comparisons](/docs/comparisons) if you're interested.
|
||||
|
||||
### Documentation
|
||||
|
||||
Fumadocs focuses on **authoring experience**, it provides a beautiful theme and many docs automation tools.
|
||||
|
||||
It helps you to iterate your codebase faster while never leaving your docs behind.
|
||||
You can take this site as an example of docs site built with Fumadocs.
|
||||
|
||||
### Blog sites
|
||||
|
||||
Since Next.js is already a powerful framework, most features can be implemented with **just Next.js**.
|
||||
|
||||
Fumadocs provides additional tooling for Next.js, including syntax highlighting, document search, and a default theme (Fumadocs UI).
|
||||
It helps you to avoid reinventing the wheels.
|
||||
|
||||
## When to use Fumadocs
|
||||
|
||||
For most of the web applications, vanilla React.js is no longer enough.
|
||||
Nowadays, we also wish to have a blog, a showcase page, a FAQ page, etc. With a
|
||||
fancy UI that's breathtaking, in these cases, Fumadocs can help you build the
|
||||
docs easier, with less boilerplate.
|
||||
|
||||
Fumadocs is maintained by Fuma and many contributors, with care on the maintainability of codebase.
|
||||
While we don't aim to offer every functionality people wanted, we're more focused on making basic features perfect and well-maintained.
|
||||
You can also help Fumadocs to be more useful by contributing!
|
||||
60
content/blog/what-is-fumadocs.zh.mdx
Normal file
60
content/blog/what-is-fumadocs.zh.mdx
Normal file
@ -0,0 +1,60 @@
|
||||
---
|
||||
title: 什么是 Fumadocs
|
||||
description: 介绍 Fumadocs，一个可以打破常规的文档框架
|
||||
image: /images/blog/boilerplatehunt-og.png
|
||||
date: 2024-11-24T12:00:00.000Z
|
||||
published: true
|
||||
categories: [company, product]
|
||||
author: mksaas
|
||||
---
|
||||
|
||||
Fumadocs 的创建是因为我想要一种更加可定制化的文档构建体验，一个不固执己见的文档框架，**一个你可以"打破"的"框架"**。
|
||||
|
||||
## 理念
|
||||
|
||||
**更少的抽象：** Fumadocs 期望您编写代码并与您的其余软件协作。
|
||||
虽然大多数框架都是通过配置文件进行配置，但当您希望调整其细节时，它们通常缺乏灵活性。
|
||||
您无法控制它们如何渲染页面或内部逻辑。Fumadocs 向您展示应用程序如何工作，而不是仅提供单一的配置文件。
|
||||
|
||||
**Next.js 基础：** 它为您提供实用工具和美观的 UI。
|
||||
您仍然使用 Next.js App Router 的功能，如**静态站点生成**。对于 Next.js 开发者来说没有新的东西，所以您可以放心使用。
|
||||
|
||||
**对 UI 有自己的看法：** Fumadocs UI（默认主题）提供的唯一东西是**用户界面**。UI 的设计理念是提供更好的移动响应性和用户体验。
|
||||
相反，我们使用受 Shadcn UI 启发的更灵活的方法 — [Fumadocs CLI](/docs/cli)，这样我们可以快速迭代设计，并欢迎更多关于 UI 的反馈。
|
||||
|
||||
## 为什么选择 Fumadocs
|
||||
|
||||
Fumadocs 的设计考虑了灵活性。
|
||||
|
||||
您可以将 `fumadocs-core` 用作无头 UI 库并带来您自己的样式。
|
||||
Fumadocs MDX 也是处理 Next.js 中 MDX 内容的有用库。它还包括：
|
||||
|
||||
- 许多内置组件。
|
||||
- Typescript Twoslash、OpenAPI 和 Math (KaTeX) 集成。
|
||||
- 默认情况下快速且优化，原生构建在 App Router 上。
|
||||
- 与 Next.js 紧密集成，您可以轻松将其添加到现有的 Next.js 项目中。
|
||||
|
||||
如果您感兴趣，可以阅读 [比较](/docs/comparisons)。
|
||||
|
||||
### 文档
|
||||
|
||||
Fumadocs 专注于**创作体验**，它提供了一个漂亮的主题和许多文档自动化工具。
|
||||
|
||||
它帮助您更快地迭代代码库，同时不会落下您的文档。
|
||||
您可以将此站点作为使用 Fumadocs 构建的文档站点的示例。
|
||||
|
||||
### 博客站点
|
||||
|
||||
由于 Next.js 已经是一个强大的框架，大多数功能可以**仅使用 Next.js** 实现。
|
||||
|
||||
Fumadocs 为 Next.js 提供了额外的工具，包括语法高亮、文档搜索和默认主题（Fumadocs UI）。
|
||||
它帮助您避免重新发明轮子。
|
||||
|
||||
## 何时使用 Fumadocs
|
||||
|
||||
对于大多数 Web 应用程序，原生 React.js 已经不够用了。
|
||||
如今，我们还希望有一个博客、展示页面、FAQ 页面等。带有令人惊叹的精美 UI，在这些情况下，Fumadocs 可以帮助您更轻松地构建文档，减少样板代码。
|
||||
|
||||
Fumadocs 由 Fuma 和许多贡献者维护，关注代码库的可维护性。
|
||||
虽然我们不打算提供人们想要的每一项功能，但我们更专注于使基本功能完美且维护良好。
|
||||
您也可以通过贡献来帮助 Fumadocs 变得更加有用！
|
||||
@ -1,215 +0,0 @@
|
||||
---
|
||||
title: What is HaiTang?
|
||||
description: Learn Chinese ancient poetry and literature online.
|
||||
image: /images/blog/haitang-og.png
|
||||
date: 2024-10-26T12:00:00.000Z
|
||||
published: true
|
||||
categories: [company, news]
|
||||
author: haitang
|
||||
locale: en
|
||||
---
|
||||
|
||||
Until now, trying to style an article, document, or blog post with Tailwind has been a tedious task that required a keen eye for typography and a lot of complex custom CSS.
|
||||
|
||||
By default, Tailwind removes all of the default browser styling from paragraphs, headings, lists and more. This ends up being really useful for building application UIs because you spend less time undoing user-agent styles, but when you _really are_ just trying to style some content that came from a rich-text editor in a CMS or a markdown file, it can be surprising and unintuitive.
|
||||
|
||||
We get lots of complaints about it actually, with people regularly asking us things like:
|
||||
|
||||
> Why is Tailwind removing the default styles on my `h1` elements? How do I disable this? What do you mean I lose all the other base styles too?
|
||||
> We hear you, but we're not convinced that simply disabling our base styles is what you really want. You don't want to have to remove annoying margins every time you use a `p` element in a piece of your dashboard UI. And I doubt you really want your blog posts to use the user-agent styles either — you want them to look _awesome_, not awful.
|
||||
|
||||
The `@tailwindcss/typography` plugin is our attempt to give you what you _actually_ want, without any of the downsides of doing something stupid like disabling our base styles.
|
||||
|
||||
It adds a new `prose` class that you can slap on any block of vanilla HTML content and turn it into a beautiful, well-formatted document:
|
||||
|
||||
```html
|
||||
<article class="prose">
|
||||
<h1>Garlic bread with cheese: What the science tells us</h1>
|
||||
<p>
|
||||
For years parents have espoused the health benefits of eating garlic bread
|
||||
with cheese to their children, with the food earning such an iconic status
|
||||
in our culture that kids will often dress up as warm, cheesy loaf for
|
||||
Halloween.
|
||||
</p>
|
||||
<p>
|
||||
But a recent study shows that the celebrated appetizer may be linked to a
|
||||
series of rabies cases springing up around the country.
|
||||
</p>
|
||||
</article>
|
||||
```
|
||||
|
||||
For more information about how to use the plugin and the features it includes, [read the documentation](https://github.com/tailwindcss/typography/blob/master/README.md).
|
||||
|
||||
---
|
||||
|
||||
## What to expect from here on out
|
||||
|
||||
What follows from here is just a bunch of absolute nonsense I've written to dogfood the plugin itself. It includes every sensible typographic element I could think of, like **bold text**, unordered lists, ordered lists, code blocks, block quotes, _and even italics_.
|
||||
|
||||
It's important to cover all of these use cases for a few reasons:
|
||||
|
||||
1. We want everything to look good out of the box.
|
||||
2. Really just the first reason, that's the whole point of the plugin.
|
||||
3. Here's a third pretend reason though a list with three items looks more realistic than a list with two items.
|
||||
|
||||
Now we're going to try out another header style.
|
||||
|
||||
### Typography should be easy
|
||||
|
||||
So that's a header for you — with any luck if we've done our job correctly that will look pretty reasonable.
|
||||
|
||||
Something a wise person once told me about typography is:
|
||||
|
||||
> Typography is pretty important if you don't want your stuff to look like trash. Make it good then it won't be bad.
|
||||
|
||||
It's probably important that images look okay here by default as well:
|
||||
|
||||
<img
|
||||
src="/images/blog/mksaas-og.png"
|
||||
width="718"
|
||||
height="404"
|
||||
alt="Image"
|
||||
/>
|
||||
|
||||
Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old.
|
||||
|
||||
Now I'm going to show you an example of an unordered list to make sure that looks good, too:
|
||||
|
||||
- So here is the first item in this list.
|
||||
- In this example we're keeping the items short.
|
||||
- Later, we'll use longer, more complex list items.
|
||||
|
||||
And that's the end of this section.
|
||||
|
||||
## What if we stack headings?
|
||||
|
||||
### We should make sure that looks good, too.
|
||||
|
||||
Sometimes you have headings directly underneath each other. In those cases you often have to undo the top margin on the second heading because it usually looks better for the headings to be closer together than a paragraph followed by a heading should be.
|
||||
|
||||
### When a heading comes after a paragraph …
|
||||
|
||||
When a heading comes after a paragraph, we need a bit more space, like I already mentioned above. Now let's see what a more complex list would look like.
|
||||
|
||||
- **I often do this thing where list items have headings.**
|
||||
|
||||
For some reason I think this looks cool which is unfortunate because it's pretty annoying to get the styles right.
|
||||
|
||||
I often have two or three paragraphs in these list items, too, so the hard part is getting the spacing between the paragraphs, list item heading, and separate list items to all make sense. Pretty tough honestly, you could make a strong argument that you just shouldn't write this way.
|
||||
|
||||
- **Since this is a list, I need at least two items.**
|
||||
|
||||
I explained what I'm doing already in the previous list item, but a list wouldn't be a list if it only had one item, and we really want this to look realistic. That's why I've added this second list item so I actually have something to look at when writing the styles.
|
||||
|
||||
- **It's not a bad idea to add a third item either.**
|
||||
|
||||
I think it probably would've been fine to just use two items but three is definitely not worse, and since I seem to be having no trouble making up arbitrary things to type, I might as well include it.
|
||||
|
||||
After this sort of list I usually have a closing statement or paragraph, because it kinda looks weird jumping right to a heading.
|
||||
|
||||
## Code should look okay by default.
|
||||
|
||||
I think most people are going to use [highlight.js](https://highlightjs.org/) or [Prism](https://prismjs.com/) or something if they want to style their code blocks but it wouldn't hurt to make them look _okay_ out of the box, even with no syntax highlighting.
|
||||
|
||||
Here's what a default `tailwind.config.js` file looks like at the time of writing:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
purge: [],
|
||||
theme: {
|
||||
extend: {},
|
||||
},
|
||||
variants: {},
|
||||
plugins: [],
|
||||
};
|
||||
```
|
||||
|
||||
Hopefully that looks good enough to you.
|
||||
|
||||
### What about nested lists?
|
||||
|
||||
Nested lists basically always look bad which is why editors like Medium don't even let you do it, but I guess since some of you goofballs are going to do it we have to carry the burden of at least making it work.
|
||||
|
||||
1. **Nested lists are rarely a good idea.**
|
||||
- You might feel like you are being really "organized" or something but you are just creating a gross shape on the screen that is hard to read.
|
||||
- Nested navigation in UIs is a bad idea too, keep things as flat as possible.
|
||||
- Nesting tons of folders in your source code is also not helpful.
|
||||
2. **Since we need to have more items, here's another one.**
|
||||
- I'm not sure if we'll bother styling more than two levels deep.
|
||||
- Two is already too much, three is guaranteed to be a bad idea.
|
||||
- If you nest four levels deep you belong in prison.
|
||||
3. **Two items isn't really a list, three is good though.**
|
||||
- Again please don't nest lists if you want people to actually read your content.
|
||||
- Nobody wants to look at this.
|
||||
- I'm upset that we even have to bother styling this.
|
||||
|
||||
The most annoying thing about lists in Markdown is that `<li>` elements aren't given a child `<p>` tag unless there are multiple paragraphs in the list item. That means I have to worry about styling that annoying situation too.
|
||||
|
||||
- **For example, here's another nested list.**
|
||||
|
||||
But this time with a second paragraph.
|
||||
|
||||
- These list items won't have `<p>` tags
|
||||
- Because they are only one line each
|
||||
|
||||
- **But in this second top-level list item, they will.**
|
||||
|
||||
This is especially annoying because of the spacing on this paragraph.
|
||||
|
||||
- As you can see here, because I've added a second line, this list item now has a `<p>` tag.
|
||||
|
||||
This is the second line I'm talking about by the way.
|
||||
|
||||
- Finally here's another list item so it's more like a list.
|
||||
|
||||
- A closing list item, but with no nested list, because why not?
|
||||
|
||||
And finally a sentence to close off this section.
|
||||
|
||||
## There are other elements we need to style
|
||||
|
||||
I almost forgot to mention links, like [this link to the Tailwind CSS website](https://tailwindcss.com). We almost made them blue but that's so yesterday, so we went with dark gray, feels edgier.
|
||||
|
||||
We even included table styles, check it out:
|
||||
|
||||
| Wrestler | Origin | Finisher |
|
||||
| ----------------------- | ------------ | ------------------ |
|
||||
| Bret "The Hitman" Hart | Calgary, AB | Sharpshooter |
|
||||
| Stone Cold Steve Austin | Austin, TX | Stone Cold Stunner |
|
||||
| Randy Savage | Sarasota, FL | Elbow Drop |
|
||||
| Vader | Boulder, CO | Vader Bomb |
|
||||
| Razor Ramon | Chuluota, FL | Razor's Edge |
|
||||
|
||||
We also need to make sure inline code looks good, like if I wanted to talk about `<span>` elements or tell you the good news about `@tailwindcss/typography`.
|
||||
|
||||
### Sometimes I even use `code` in headings
|
||||
|
||||
Even though it's probably a bad idea, and historically I've had a hard time making it look good. This _"wrap the code blocks in backticks"_ trick works pretty well though really.
|
||||
|
||||
Another thing I've done in the past is put a `code` tag inside of a link, like if I wanted to tell you about the [`tailwindcss/docs`](https://github.com/tailwindcss/docs) repository. I don't love that there is an underline below the backticks but it is absolutely not worth the madness it would require to avoid it.
|
||||
|
||||
#### We haven't used an `h4` yet
|
||||
|
||||
But now we have. Please don't use `h5` or `h6` in your content, Medium only supports two heading levels for a reason, you animals. I honestly considered using a `before` pseudo-element to scream at you if you use an `h5` or `h6`.
|
||||
|
||||
We don't style them at all out of the box because `h4` elements are already so small that they are the same size as the body copy. What are we supposed to do with an `h5`, make it _smaller_ than the body copy? No thanks.
|
||||
|
||||
### We still need to think about stacked headings though.
|
||||
|
||||
#### Let's make sure we don't screw that up with `h4` elements, either.
|
||||
|
||||
Phew, with any luck we have styled the headings above this text and they look pretty good.
|
||||
|
||||
Let's add a closing paragraph here so things end with a decently sized block of text. I can't explain why I want things to end that way but I have to assume it's because I think things will look weird or unbalanced if there is a heading too close to the end of the document.
|
||||
|
||||
What I've written here is probably long enough, but adding this final sentence can't hurt.
|
||||
|
||||
## GitHub Flavored Markdown
|
||||
|
||||
I've also added support for GitHub Flavored Mardown using `remark-gfm`.
|
||||
|
||||
With `remark-gfm`, we get a few extra features in our markdown. Example: autolink literals.
|
||||
|
||||
A link like www.example.com or https://example.com would automatically be converted into an `a` tag.
|
||||
|
||||
This works for email links too: contact@example.com.
|
||||
@ -1,215 +0,0 @@
|
||||
---
|
||||
title: HaiTang 是什么？
|
||||
description: 海棠诗社，中华古诗词的数字桃源。
|
||||
image: /images/blog/haitang-og.png
|
||||
date: 2024-10-26T12:00:00.000Z
|
||||
published: true
|
||||
categories: [company, news]
|
||||
author: haitang
|
||||
locale: zh
|
||||
---
|
||||
|
||||
到目前为止，尝试使用 Tailwind 来设计文章、文档或博客文章的样式一直是一项繁琐的任务，需要对排版有敏锐的眼光，并且需要大量复杂的自定义 CSS。
|
||||
|
||||
默认情况下，Tailwind 会删除段落、标题、列表等所有默认的浏览器样式。这对于构建应用程序 UI 非常有用，因为您花更少的时间撤销用户代理样式，但是当您真的只是尝试设置来自 CMS 中富文本编辑器或 markdown 文件的内容的样式时，这可能会令人惊讶和不直观。
|
||||
|
||||
我们实际上收到了很多关于它的投诉，人们经常问我们这样的问题：
|
||||
|
||||
> 为什么 Tailwind 删除了我的 `h1` 元素上的默认样式？我如何禁用这个？你说我也会失去所有其他基本样式是什么意思？
|
||||
> 我们听到了您的声音，但我们并不确信简单地禁用我们的基本样式就是您真正想要的。您不希望每次在仪表板 UI 的一部分中使用 `p` 元素时都必须删除烦人的边距。而且我怀疑您真的希望您的博客文章使用用户代理样式——您希望它们看起来很棒，而不是糟糕。
|
||||
|
||||
`@tailwindcss/typography` 插件是我们尝试给您真正想要的东西，而不会有做一些愚蠢的事情（比如禁用我们的基本样式）的任何缺点。
|
||||
|
||||
它添加了一个新的 `prose` 类，您可以将其应用于任何普通 HTML 内容块，并将其转变为一个美丽、格式良好的文档：
|
||||
|
||||
```html
|
||||
<article class="prose">
|
||||
<h1>Garlic bread with cheese: What the science tells us</h1>
|
||||
<p>
|
||||
For years parents have espoused the health benefits of eating garlic bread
|
||||
with cheese to their children, with the food earning such an iconic status
|
||||
in our culture that kids will often dress up as warm, cheesy loaf for
|
||||
Halloween.
|
||||
</p>
|
||||
<p>
|
||||
But a recent study shows that the celebrated appetizer may be linked to a
|
||||
series of rabies cases springing up around the country.
|
||||
</p>
|
||||
</article>
|
||||
```
|
||||
|
||||
有关如何使用该插件及其包含的功能的更多信息，[阅读文档](https://github.com/tailwindcss/typography/blob/master/README.md)。
|
||||
|
||||
---
|
||||
|
||||
## 从现在开始期待什么
|
||||
|
||||
从这里开始的是我写的一堆绝对无意义的内容，用来测试插件本身。它包括我能想到的每一个合理的排版元素，如**粗体文本**、无序列表、有序列表、代码块、块引用，_甚至斜体_。
|
||||
|
||||
涵盖所有这些用例很重要，原因如下：
|
||||
|
||||
1. 我们希望一切开箱即用看起来都很好。
|
||||
2. 实际上只是第一个原因，这是插件的全部意义。
|
||||
3. 这里有第三个假装的原因，尽管一个有三个项目的列表看起来比一个有两个项目的列表更真实。
|
||||
|
||||
现在我们将尝试另一种标题样式。
|
||||
|
||||
### 排版应该很简单
|
||||
|
||||
所以这是给你的一个标题——如果我们做得正确，那应该看起来相当合理。
|
||||
|
||||
一位智者曾经告诉我关于排版的一件事是：
|
||||
|
||||
> 如果你不希望你的东西看起来像垃圾，排版是非常重要的。做好它，那么它就不会糟糕。
|
||||
|
||||
默认情况下，图片在这里看起来也应该不错：
|
||||
|
||||
<img
|
||||
src="/images/blog/mksaas-og.png"
|
||||
width="718"
|
||||
height="404"
|
||||
alt="图片"
|
||||
/>
|
||||
|
||||
与普遍的看法相反，Lorem Ipsum 并不是简单的随机文本。它起源于公元前 45 年的一段古典拉丁文学，使其有超过 2000 年的历史。
|
||||
|
||||
现在我将向您展示一个无序列表的例子，以确保它看起来也不错：
|
||||
|
||||
- 所以这是这个列表中的第一项。
|
||||
- 在这个例子中，我们保持项目简短。
|
||||
- 稍后，我们将使用更长、更复杂的列表项。
|
||||
|
||||
这就是本节的结尾。
|
||||
|
||||
## 如果我们堆叠标题怎么办？
|
||||
|
||||
### 我们也应该确保这看起来不错。
|
||||
|
||||
有时候你有直接堆叠在一起的标题。在这些情况下，你通常必须取消第二个标题上的顶部边距，因为标题彼此靠得更近通常看起来比段落后面跟着标题要好。
|
||||
|
||||
### 当标题在段落之后出现时……
|
||||
|
||||
当标题在段落之后出现时，我们需要更多的空间，就像我上面已经提到的那样。现在让我们看看一个更复杂的列表会是什么样子。
|
||||
|
||||
- **我经常做这种事，列表项有标题。**
|
||||
|
||||
由于某种原因，我认为这看起来很酷，这很不幸，因为要让样式正确是相当烦人的。
|
||||
|
||||
我在这些列表项中通常也有两到三个段落，所以困难的部分是让段落之间的间距、列表项标题和单独的列表项都有意义。老实说，这很困难，你可以提出一个强有力的论点，认为你根本不应该这样写。
|
||||
|
||||
- **由于这是一个列表，我至少需要两个项目。**
|
||||
|
||||
我已经在前面的列表项中解释了我在做什么，但是如果一个列表只有一个项目，那就不是一个列表，我们真的希望这看起来真实。这就是为什么我添加了这第二个列表项，所以我在写样式时实际上有东西可以看。
|
||||
|
||||
- **添加第三项也不是一个坏主意。**
|
||||
|
||||
我认为只使用两个项目可能已经足够了，但三个肯定不会更糟，而且由于我似乎在编造任意的东西时没有遇到麻烦，我不妨包括它。
|
||||
|
||||
在这种列表之后，我通常会有一个结束语或段落，因为直接跳到标题看起来有点奇怪。
|
||||
|
||||
## 代码默认应该看起来不错。
|
||||
|
||||
我认为大多数人如果想要设置他们的代码块的样式，会使用 [highlight.js](https://highlightjs.org/) 或 [Prism](https://prismjs.com/) 或其他东西，但是让它们开箱即用看起来_还不错_，即使没有语法高亮，也不会有害。
|
||||
|
||||
以下是撰写本文时默认的 `tailwind.config.js` 文件的样子：
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
purge: [],
|
||||
theme: {
|
||||
extend: {},
|
||||
},
|
||||
variants: {},
|
||||
plugins: [],
|
||||
};
|
||||
```
|
||||
|
||||
希望这对你来说看起来足够好。
|
||||
|
||||
### 嵌套列表怎么办？
|
||||
|
||||
嵌套列表基本上总是看起来很糟糕，这就是为什么像 Medium 这样的编辑器甚至不让你这样做，但我猜既然你们中的一些傻瓜要这样做，我们至少要承担让它工作的负担。
|
||||
|
||||
1. **嵌套列表很少是一个好主意。**
|
||||
- 你可能觉得你真的很"有组织"或者什么的，但你只是在屏幕上创建一个难以阅读的粗糙形状。
|
||||
- UI 中的嵌套导航也是一个坏主意，尽可能保持扁平。
|
||||
- 在源代码中嵌套大量文件夹也没有帮助。
|
||||
2. **既然我们需要有更多的项目，这里有另一个。**
|
||||
- 我不确定我们是否会费心设置超过两级深度的样式。
|
||||
- 两级已经太多了，三级肯定是一个坏主意。
|
||||
- 如果你嵌套四级深度，你应该进监狱。
|
||||
3. **两个项目并不是真正的列表，三个项目就好了。**
|
||||
- 再次请不要嵌套列表，如果你希望人们真正阅读你的内容。
|
||||
- 没有人想看这个。
|
||||
- 我很不高兴我们甚至必须费心设置这个样式。
|
||||
|
||||
Markdown 中列表最烦人的事情是，除非列表项中有多个段落，否则 `<li>` 元素不会被赋予子 `<p>` 标签。这意味着我也必须担心设置那种烦人情况的样式。
|
||||
|
||||
- **例如，这里是另一个嵌套列表。**
|
||||
|
||||
但这次有第二段。
|
||||
|
||||
- 这些列表项不会有 `<p>` 标签
|
||||
- 因为它们每个只有一行
|
||||
|
||||
- **但在这第二个顶级列表项中，它们会有。**
|
||||
|
||||
这特别烦人，因为这段话的间距。
|
||||
|
||||
- 正如你在这里看到的，因为我添加了第二行，这个列表项现在有一个 `<p>` 标签。
|
||||
|
||||
顺便说一下，这是我说的第二行。
|
||||
|
||||
- 最后这里有另一个列表项，所以它更像一个列表。
|
||||
|
||||
- 一个结束列表项，但没有嵌套列表，为什么不呢？
|
||||
|
||||
最后一句话结束这一节。
|
||||
|
||||
## 还有其他我们需要设置样式的元素
|
||||
|
||||
我几乎忘了提到链接，比如[这个链接到 Tailwind CSS 网站](https://tailwindcss.com)。我们几乎把它们变成蓝色，但那是昨天的事了，所以我们选择了深灰色，感觉更前卫。
|
||||
|
||||
我们甚至包括了表格样式，看看：
|
||||
|
||||
| 摔跤手 | 出生地 | 终结技 |
|
||||
| ----------------------- | ------------- | ------------------- |
|
||||
| Bret "The Hitman" Hart | Calgary, AB | Sharpshooter |
|
||||
| Stone Cold Steve Austin | Austin, TX | Stone Cold Stunner |
|
||||
| Randy Savage | Sarasota, FL | Elbow Drop |
|
||||
| Vader | Boulder, CO | Vader Bomb |
|
||||
| Razor Ramon | Chuluota, FL | Razor's Edge |
|
||||
|
||||
我们还需要确保内联代码看起来不错，比如如果我想谈论 `<span>` 元素或者告诉你关于 `@tailwindcss/typography` 的好消息。
|
||||
|
||||
### 有时我甚至在标题中使用 `code`
|
||||
|
||||
尽管这可能是一个坏主意，而且历史上我一直很难让它看起来不错。不过这个_"将代码块包裹在反引号中"_的技巧效果相当不错。
|
||||
|
||||
我过去做过的另一件事是在链接中放置一个 `code` 标签，比如如果我想告诉你关于 [`tailwindcss/docs`](https://github.com/tailwindcss/docs) 仓库的事情。我不喜欢反引号下面有下划线，但为了避免它而导致的疯狂绝对不值得。
|
||||
|
||||
#### 我们还没有使用 `h4`
|
||||
|
||||
但现在我们有了。请不要在你的内容中使用 `h5` 或 `h6`，Medium 只支持两个标题级别是有原因的，你们这些动物。我老实说考虑过使用 `before` 伪元素，如果你使用 `h5` 或 `h6` 就对你大喊大叫。
|
||||
|
||||
我们根本不会为它们设置样式，因为 `h4` 元素已经很小，与正文大小相同。我们应该怎么处理 `h5`，让它比正文更_小_？不，谢谢。
|
||||
|
||||
### 不过我们仍然需要考虑堆叠的标题。
|
||||
|
||||
#### 让我们确保我们也不会用 `h4` 元素搞砸这个。
|
||||
|
||||
呼，运气好的话，我们已经设置了上面这段文字的标题样式，它们看起来相当不错。
|
||||
|
||||
让我们在这里添加一个结束段落，这样事情就会以一个相当大小的文本块结束。我无法解释为什么我希望事情以这种方式结束，但我必须假设这是因为我认为如果文档末尾太靠近标题，事情会看起来奇怪或不平衡。
|
||||
|
||||
我在这里写的可能已经足够长了，但添加这最后一句话不会有害。
|
||||
|
||||
## GitHub 风格的 Markdown
|
||||
|
||||
我还添加了对使用 `remark-gfm` 的 GitHub 风格 Markdown 的支持。
|
||||
|
||||
使用 `remark-gfm`，我们在 markdown 中获得了一些额外的功能。例如：自动链接文字。
|
||||
|
||||
像 www.example.com 或 https://example.com 这样的链接会自动转换为 `a` 标签。
|
||||
|
||||
这对电子邮件链接也有效：contact@example.com。
|
||||
@ -1,214 +0,0 @@
|
||||
---
|
||||
title: What is IndieHub?
|
||||
description: IndieHub is the best all-in-one directory for indie hackers.
|
||||
image: /images/blog/indiehub-og.png
|
||||
date: 2024-11-24T12:00:00.000Z
|
||||
published: true
|
||||
categories: [news, product]
|
||||
author: indiehub
|
||||
---
|
||||
|
||||
Until now, trying to style an article, document, or blog post with Tailwind has been a tedious task that required a keen eye for typography and a lot of complex custom CSS.
|
||||
|
||||
By default, Tailwind removes all of the default browser styling from paragraphs, headings, lists and more. This ends up being really useful for building application UIs because you spend less time undoing user-agent styles, but when you _really are_ just trying to style some content that came from a rich-text editor in a CMS or a markdown file, it can be surprising and unintuitive.
|
||||
|
||||
We get lots of complaints about it actually, with people regularly asking us things like:
|
||||
|
||||
> Why is Tailwind removing the default styles on my `h1` elements? How do I disable this? What do you mean I lose all the other base styles too?
|
||||
> We hear you, but we're not convinced that simply disabling our base styles is what you really want. You don't want to have to remove annoying margins every time you use a `p` element in a piece of your dashboard UI. And I doubt you really want your blog posts to use the user-agent styles either — you want them to look _awesome_, not awful.
|
||||
|
||||
The `@tailwindcss/typography` plugin is our attempt to give you what you _actually_ want, without any of the downsides of doing something stupid like disabling our base styles.
|
||||
|
||||
It adds a new `prose` class that you can slap on any block of vanilla HTML content and turn it into a beautiful, well-formatted document:
|
||||
|
||||
```html
|
||||
<article class="prose">
|
||||
<h1>Garlic bread with cheese: What the science tells us</h1>
|
||||
<p>
|
||||
For years parents have espoused the health benefits of eating garlic bread
|
||||
with cheese to their children, with the food earning such an iconic status
|
||||
in our culture that kids will often dress up as warm, cheesy loaf for
|
||||
Halloween.
|
||||
</p>
|
||||
<p>
|
||||
But a recent study shows that the celebrated appetizer may be linked to a
|
||||
series of rabies cases springing up around the country.
|
||||
</p>
|
||||
</article>
|
||||
```
|
||||
|
||||
For more information about how to use the plugin and the features it includes, [read the documentation](https://github.com/tailwindcss/typography/blob/master/README.md).
|
||||
|
||||
---
|
||||
|
||||
## What to expect from here on out
|
||||
|
||||
What follows from here is just a bunch of absolute nonsense I've written to dogfood the plugin itself. It includes every sensible typographic element I could think of, like **bold text**, unordered lists, ordered lists, code blocks, block quotes, _and even italics_.
|
||||
|
||||
It's important to cover all of these use cases for a few reasons:
|
||||
|
||||
1. We want everything to look good out of the box.
|
||||
2. Really just the first reason, that's the whole point of the plugin.
|
||||
3. Here's a third pretend reason though a list with three items looks more realistic than a list with two items.
|
||||
|
||||
Now we're going to try out another header style.
|
||||
|
||||
### Typography should be easy
|
||||
|
||||
So that's a header for you — with any luck if we've done our job correctly that will look pretty reasonable.
|
||||
|
||||
Something a wise person once told me about typography is:
|
||||
|
||||
> Typography is pretty important if you don't want your stuff to look like trash. Make it good then it won't be bad.
|
||||
|
||||
It's probably important that images look okay here by default as well:
|
||||
|
||||
<img
|
||||
src="/images/blog/mksaas-og.png"
|
||||
width="718"
|
||||
height="404"
|
||||
alt="Image"
|
||||
/>
|
||||
|
||||
Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old.
|
||||
|
||||
Now I'm going to show you an example of an unordered list to make sure that looks good, too:
|
||||
|
||||
- So here is the first item in this list.
|
||||
- In this example we're keeping the items short.
|
||||
- Later, we'll use longer, more complex list items.
|
||||
|
||||
And that's the end of this section.
|
||||
|
||||
## What if we stack headings?
|
||||
|
||||
### We should make sure that looks good, too.
|
||||
|
||||
Sometimes you have headings directly underneath each other. In those cases you often have to undo the top margin on the second heading because it usually looks better for the headings to be closer together than a paragraph followed by a heading should be.
|
||||
|
||||
### When a heading comes after a paragraph …
|
||||
|
||||
When a heading comes after a paragraph, we need a bit more space, like I already mentioned above. Now let's see what a more complex list would look like.
|
||||
|
||||
- **I often do this thing where list items have headings.**
|
||||
|
||||
For some reason I think this looks cool which is unfortunate because it's pretty annoying to get the styles right.
|
||||
|
||||
I often have two or three paragraphs in these list items, too, so the hard part is getting the spacing between the paragraphs, list item heading, and separate list items to all make sense. Pretty tough honestly, you could make a strong argument that you just shouldn't write this way.
|
||||
|
||||
- **Since this is a list, I need at least two items.**
|
||||
|
||||
I explained what I'm doing already in the previous list item, but a list wouldn't be a list if it only had one item, and we really want this to look realistic. That's why I've added this second list item so I actually have something to look at when writing the styles.
|
||||
|
||||
- **It's not a bad idea to add a third item either.**
|
||||
|
||||
I think it probably would've been fine to just use two items but three is definitely not worse, and since I seem to be having no trouble making up arbitrary things to type, I might as well include it.
|
||||
|
||||
After this sort of list I usually have a closing statement or paragraph, because it kinda looks weird jumping right to a heading.
|
||||
|
||||
## Code should look okay by default.
|
||||
|
||||
I think most people are going to use [highlight.js](https://highlightjs.org/) or [Prism](https://prismjs.com/) or something if they want to style their code blocks but it wouldn't hurt to make them look _okay_ out of the box, even with no syntax highlighting.
|
||||
|
||||
Here's what a default `tailwind.config.js` file looks like at the time of writing:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
purge: [],
|
||||
theme: {
|
||||
extend: {},
|
||||
},
|
||||
variants: {},
|
||||
plugins: [],
|
||||
};
|
||||
```
|
||||
|
||||
Hopefully that looks good enough to you.
|
||||
|
||||
### What about nested lists?
|
||||
|
||||
Nested lists basically always look bad which is why editors like Medium don't even let you do it, but I guess since some of you goofballs are going to do it we have to carry the burden of at least making it work.
|
||||
|
||||
1. **Nested lists are rarely a good idea.**
|
||||
- You might feel like you are being really "organized" or something but you are just creating a gross shape on the screen that is hard to read.
|
||||
- Nested navigation in UIs is a bad idea too, keep things as flat as possible.
|
||||
- Nesting tons of folders in your source code is also not helpful.
|
||||
2. **Since we need to have more items, here's another one.**
|
||||
- I'm not sure if we'll bother styling more than two levels deep.
|
||||
- Two is already too much, three is guaranteed to be a bad idea.
|
||||
- If you nest four levels deep you belong in prison.
|
||||
3. **Two items isn't really a list, three is good though.**
|
||||
- Again please don't nest lists if you want people to actually read your content.
|
||||
- Nobody wants to look at this.
|
||||
- I'm upset that we even have to bother styling this.
|
||||
|
||||
The most annoying thing about lists in Markdown is that `<li>` elements aren't given a child `<p>` tag unless there are multiple paragraphs in the list item. That means I have to worry about styling that annoying situation too.
|
||||
|
||||
- **For example, here's another nested list.**
|
||||
|
||||
But this time with a second paragraph.
|
||||
|
||||
- These list items won't have `<p>` tags
|
||||
- Because they are only one line each
|
||||
|
||||
- **But in this second top-level list item, they will.**
|
||||
|
||||
This is especially annoying because of the spacing on this paragraph.
|
||||
|
||||
- As you can see here, because I've added a second line, this list item now has a `<p>` tag.
|
||||
|
||||
This is the second line I'm talking about by the way.
|
||||
|
||||
- Finally here's another list item so it's more like a list.
|
||||
|
||||
- A closing list item, but with no nested list, because why not?
|
||||
|
||||
And finally a sentence to close off this section.
|
||||
|
||||
## There are other elements we need to style
|
||||
|
||||
I almost forgot to mention links, like [this link to the Tailwind CSS website](https://tailwindcss.com). We almost made them blue but that's so yesterday, so we went with dark gray, feels edgier.
|
||||
|
||||
We even included table styles, check it out:
|
||||
|
||||
| Wrestler | Origin | Finisher |
|
||||
| ----------------------- | ------------ | ------------------ |
|
||||
| Bret "The Hitman" Hart | Calgary, AB | Sharpshooter |
|
||||
| Stone Cold Steve Austin | Austin, TX | Stone Cold Stunner |
|
||||
| Randy Savage | Sarasota, FL | Elbow Drop |
|
||||
| Vader | Boulder, CO | Vader Bomb |
|
||||
| Razor Ramon | Chuluota, FL | Razor's Edge |
|
||||
|
||||
We also need to make sure inline code looks good, like if I wanted to talk about `<span>` elements or tell you the good news about `@tailwindcss/typography`.
|
||||
|
||||
### Sometimes I even use `code` in headings
|
||||
|
||||
Even though it's probably a bad idea, and historically I've had a hard time making it look good. This _"wrap the code blocks in backticks"_ trick works pretty well though really.
|
||||
|
||||
Another thing I've done in the past is put a `code` tag inside of a link, like if I wanted to tell you about the [`tailwindcss/docs`](https://github.com/tailwindcss/docs) repository. I don't love that there is an underline below the backticks but it is absolutely not worth the madness it would require to avoid it.
|
||||
|
||||
#### We haven't used an `h4` yet
|
||||
|
||||
But now we have. Please don't use `h5` or `h6` in your content, Medium only supports two heading levels for a reason, you animals. I honestly considered using a `before` pseudo-element to scream at you if you use an `h5` or `h6`.
|
||||
|
||||
We don't style them at all out of the box because `h4` elements are already so small that they are the same size as the body copy. What are we supposed to do with an `h5`, make it _smaller_ than the body copy? No thanks.
|
||||
|
||||
### We still need to think about stacked headings though.
|
||||
|
||||
#### Let's make sure we don't screw that up with `h4` elements, either.
|
||||
|
||||
Phew, with any luck we have styled the headings above this text and they look pretty good.
|
||||
|
||||
Let's add a closing paragraph here so things end with a decently sized block of text. I can't explain why I want things to end that way but I have to assume it's because I think things will look weird or unbalanced if there is a heading too close to the end of the document.
|
||||
|
||||
What I've written here is probably long enough, but adding this final sentence can't hurt.
|
||||
|
||||
## GitHub Flavored Markdown
|
||||
|
||||
I've also added support for GitHub Flavored Mardown using `remark-gfm`.
|
||||
|
||||
With `remark-gfm`, we get a few extra features in our markdown. Example: autolink literals.
|
||||
|
||||
A link like www.example.com or https://example.com would automatically be converted into an `a` tag.
|
||||
|
||||
This works for email links too: contact@example.com.
|
||||
@ -1,215 +0,0 @@
|
||||
---
|
||||
title: IndieHub 是什么？
|
||||
description: IndieHub是一站式的独立开发者导航站。
|
||||
image: /images/blog/indiehub-og.png
|
||||
date: 2024-11-24T12:00:00.000Z
|
||||
published: true
|
||||
categories: [news, product]
|
||||
author: indiehub
|
||||
locale: zh
|
||||
---
|
||||
|
||||
到目前为止，尝试使用 Tailwind 来设计文章、文档或博客文章的样式一直是一项繁琐的任务，需要对排版有敏锐的眼光，并且需要大量复杂的自定义 CSS。
|
||||
|
||||
默认情况下，Tailwind 会删除段落、标题、列表等所有默认的浏览器样式。这对于构建应用程序 UI 非常有用，因为您花更少的时间撤销用户代理样式，但是当您真的只是尝试设置来自 CMS 中富文本编辑器或 markdown 文件的内容的样式时，这可能会令人惊讶和不直观。
|
||||
|
||||
我们实际上收到了很多关于它的投诉，人们经常问我们这样的问题：
|
||||
|
||||
> 为什么 Tailwind 删除了我的 `h1` 元素上的默认样式？我如何禁用这个？你说我也会失去所有其他基本样式是什么意思？
|
||||
> 我们听到了您的声音，但我们并不确信简单地禁用我们的基本样式就是您真正想要的。您不希望每次在仪表板 UI 的一部分中使用 `p` 元素时都必须删除烦人的边距。而且我怀疑您真的希望您的博客文章使用用户代理样式——您希望它们看起来很棒，而不是糟糕。
|
||||
|
||||
`@tailwindcss/typography` 插件是我们尝试给您真正想要的东西，而不会有做一些愚蠢的事情（比如禁用我们的基本样式）的任何缺点。
|
||||
|
||||
它添加了一个新的 `prose` 类，您可以将其应用于任何普通 HTML 内容块，并将其转变为一个美丽、格式良好的文档：
|
||||
|
||||
```html
|
||||
<article class="prose">
|
||||
<h1>Garlic bread with cheese: What the science tells us</h1>
|
||||
<p>
|
||||
For years parents have espoused the health benefits of eating garlic bread
|
||||
with cheese to their children, with the food earning such an iconic status
|
||||
in our culture that kids will often dress up as warm, cheesy loaf for
|
||||
Halloween.
|
||||
</p>
|
||||
<p>
|
||||
But a recent study shows that the celebrated appetizer may be linked to a
|
||||
series of rabies cases springing up around the country.
|
||||
</p>
|
||||
</article>
|
||||
```
|
||||
|
||||
有关如何使用该插件及其包含的功能的更多信息，[阅读文档](https://github.com/tailwindcss/typography/blob/master/README.md)。
|
||||
|
||||
---
|
||||
|
||||
## 从现在开始期待什么
|
||||
|
||||
从这里开始的是我写的一堆绝对无意义的内容，用来测试插件本身。它包括我能想到的每一个合理的排版元素，如**粗体文本**、无序列表、有序列表、代码块、块引用，_甚至斜体_。
|
||||
|
||||
涵盖所有这些用例很重要，原因如下：
|
||||
|
||||
1. 我们希望一切开箱即用看起来都很好。
|
||||
2. 实际上只是第一个原因，这是插件的全部意义。
|
||||
3. 这里有第三个假装的原因，尽管一个有三个项目的列表看起来比一个有两个项目的列表更真实。
|
||||
|
||||
现在我们将尝试另一种标题样式。
|
||||
|
||||
### 排版应该很简单
|
||||
|
||||
所以这是给你的一个标题——如果我们做得正确，那应该看起来相当合理。
|
||||
|
||||
一位智者曾经告诉我关于排版的一件事是：
|
||||
|
||||
> 如果你不希望你的东西看起来像垃圾，排版是非常重要的。做好它，那么它就不会糟糕。
|
||||
|
||||
默认情况下，图片在这里看起来也应该不错：
|
||||
|
||||
<img
|
||||
src="/images/blog/mksaas-og.png"
|
||||
width="718"
|
||||
height="404"
|
||||
alt="图片"
|
||||
/>
|
||||
|
||||
与普遍的看法相反，Lorem Ipsum 并不是简单的随机文本。它起源于公元前 45 年的一段古典拉丁文学，使其有超过 2000 年的历史。
|
||||
|
||||
现在我将向您展示一个无序列表的例子，以确保它看起来也不错：
|
||||
|
||||
- 所以这是这个列表中的第一项。
|
||||
- 在这个例子中，我们保持项目简短。
|
||||
- 稍后，我们将使用更长、更复杂的列表项。
|
||||
|
||||
这就是本节的结尾。
|
||||
|
||||
## 如果我们堆叠标题怎么办？
|
||||
|
||||
### 我们也应该确保这看起来不错。
|
||||
|
||||
有时候你有直接堆叠在一起的标题。在这些情况下，你通常必须取消第二个标题上的顶部边距，因为标题彼此靠得更近通常看起来比段落后面跟着标题要好。
|
||||
|
||||
### 当标题在段落之后出现时……
|
||||
|
||||
当标题在段落之后出现时，我们需要更多的空间，就像我上面已经提到的那样。现在让我们看看一个更复杂的列表会是什么样子。
|
||||
|
||||
- **我经常做这种事，列表项有标题。**
|
||||
|
||||
由于某种原因，我认为这看起来很酷，这很不幸，因为要让样式正确是相当烦人的。
|
||||
|
||||
我在这些列表项中通常也有两到三个段落，所以困难的部分是让段落之间的间距、列表项标题和单独的列表项都有意义。老实说，这很困难，你可以提出一个强有力的论点，认为你根本不应该这样写。
|
||||
|
||||
- **由于这是一个列表，我至少需要两个项目。**
|
||||
|
||||
我已经在前面的列表项中解释了我在做什么，但是如果一个列表只有一个项目，那就不是一个列表，我们真的希望这看起来真实。这就是为什么我添加了这第二个列表项，所以我在写样式时实际上有东西可以看。
|
||||
|
||||
- **添加第三项也不是一个坏主意。**
|
||||
|
||||
我认为只使用两个项目可能已经足够了，但三个肯定不会更糟，而且由于我似乎在编造任意的东西时没有遇到麻烦，我不妨包括它。
|
||||
|
||||
在这种列表之后，我通常会有一个结束语或段落，因为直接跳到标题看起来有点奇怪。
|
||||
|
||||
## 代码默认应该看起来不错。
|
||||
|
||||
我认为大多数人如果想要设置他们的代码块的样式，会使用 [highlight.js](https://highlightjs.org/) 或 [Prism](https://prismjs.com/) 或其他东西，但是让它们开箱即用看起来_还不错_，即使没有语法高亮，也不会有害。
|
||||
|
||||
以下是撰写本文时默认的 `tailwind.config.js` 文件的样子：
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
purge: [],
|
||||
theme: {
|
||||
extend: {},
|
||||
},
|
||||
variants: {},
|
||||
plugins: [],
|
||||
};
|
||||
```
|
||||
|
||||
希望这对你来说看起来足够好。
|
||||
|
||||
### 嵌套列表怎么办？
|
||||
|
||||
嵌套列表基本上总是看起来很糟糕，这就是为什么像 Medium 这样的编辑器甚至不让你这样做，但我猜既然你们中的一些傻瓜要这样做，我们至少要承担让它工作的负担。
|
||||
|
||||
1. **嵌套列表很少是一个好主意。**
|
||||
- 你可能觉得你真的很"有组织"或者什么的，但你只是在屏幕上创建一个难以阅读的粗糙形状。
|
||||
- UI 中的嵌套导航也是一个坏主意，尽可能保持扁平。
|
||||
- 在源代码中嵌套大量文件夹也没有帮助。
|
||||
2. **既然我们需要有更多的项目，这里有另一个。**
|
||||
- 我不确定我们是否会费心设置超过两级深度的样式。
|
||||
- 两级已经太多了，三级肯定是一个坏主意。
|
||||
- 如果你嵌套四级深度，你应该进监狱。
|
||||
3. **两个项目并不是真正的列表，三个项目就好了。**
|
||||
- 再次请不要嵌套列表，如果你希望人们真正阅读你的内容。
|
||||
- 没有人想看这个。
|
||||
- 我很不高兴我们甚至必须费心设置这个样式。
|
||||
|
||||
Markdown 中列表最烦人的事情是，除非列表项中有多个段落，否则 `<li>` 元素不会被赋予子 `<p>` 标签。这意味着我也必须担心设置那种烦人情况的样式。
|
||||
|
||||
- **例如，这里是另一个嵌套列表。**
|
||||
|
||||
但这次有第二段。
|
||||
|
||||
- 这些列表项不会有 `<p>` 标签
|
||||
- 因为它们每个只有一行
|
||||
|
||||
- **但在这第二个顶级列表项中，它们会有。**
|
||||
|
||||
这特别烦人，因为这段话的间距。
|
||||
|
||||
- 正如你在这里看到的，因为我添加了第二行，这个列表项现在有一个 `<p>` 标签。
|
||||
|
||||
顺便说一下，这是我说的第二行。
|
||||
|
||||
- 最后这里有另一个列表项，所以它更像一个列表。
|
||||
|
||||
- 一个结束列表项，但没有嵌套列表，为什么不呢？
|
||||
|
||||
最后一句话结束这一节。
|
||||
|
||||
## 还有其他我们需要设置样式的元素
|
||||
|
||||
我几乎忘了提到链接，比如[这个链接到 Tailwind CSS 网站](https://tailwindcss.com)。我们几乎把它们变成蓝色，但那是昨天的事了，所以我们选择了深灰色，感觉更前卫。
|
||||
|
||||
我们甚至包括了表格样式，看看：
|
||||
|
||||
| 摔跤手 | 出生地 | 终结技 |
|
||||
| ----------------------- | ------------- | ------------------- |
|
||||
| Bret "The Hitman" Hart | Calgary, AB | Sharpshooter |
|
||||
| Stone Cold Steve Austin | Austin, TX | Stone Cold Stunner |
|
||||
| Randy Savage | Sarasota, FL | Elbow Drop |
|
||||
| Vader | Boulder, CO | Vader Bomb |
|
||||
| Razor Ramon | Chuluota, FL | Razor's Edge |
|
||||
|
||||
我们还需要确保内联代码看起来不错，比如如果我想谈论 `<span>` 元素或者告诉你关于 `@tailwindcss/typography` 的好消息。
|
||||
|
||||
### 有时我甚至在标题中使用 `code`
|
||||
|
||||
尽管这可能是一个坏主意，而且历史上我一直很难让它看起来不错。不过这个_"将代码块包裹在反引号中"_的技巧效果相当不错。
|
||||
|
||||
我过去做过的另一件事是在链接中放置一个 `code` 标签，比如如果我想告诉你关于 [`tailwindcss/docs`](https://github.com/tailwindcss/docs) 仓库的事情。我不喜欢反引号下面有下划线，但为了避免它而导致的疯狂绝对不值得。
|
||||
|
||||
#### 我们还没有使用 `h4`
|
||||
|
||||
但现在我们有了。请不要在你的内容中使用 `h5` 或 `h6`，Medium 只支持两个标题级别是有原因的，你们这些动物。我老实说考虑过使用 `before` 伪元素，如果你使用 `h5` 或 `h6` 就对你大喊大叫。
|
||||
|
||||
我们根本不会为它们设置样式，因为 `h4` 元素已经很小，与正文大小相同。我们应该怎么处理 `h5`，让它比正文更_小_？不，谢谢。
|
||||
|
||||
### 不过我们仍然需要考虑堆叠的标题。
|
||||
|
||||
#### 让我们确保我们也不会用 `h4` 元素搞砸这个。
|
||||
|
||||
呼，运气好的话，我们已经设置了上面这段文字的标题样式，它们看起来相当不错。
|
||||
|
||||
让我们在这里添加一个结束段落，这样事情就会以一个相当大小的文本块结束。我无法解释为什么我希望事情以这种方式结束，但我必须假设这是因为我认为如果文档末尾太靠近标题，事情会看起来奇怪或不平衡。
|
||||
|
||||
我在这里写的可能已经足够长了，但添加这最后一句话不会有害。
|
||||
|
||||
## GitHub 风格的 Markdown
|
||||
|
||||
我还添加了对使用 `remark-gfm` 的 GitHub 风格 Markdown 的支持。
|
||||
|
||||
使用 `remark-gfm`，我们在 markdown 中获得了一些额外的功能。例如：自动链接文字。
|
||||
|
||||
像 www.example.com 或 https://example.com 这样的链接会自动转换为 `a` 标签。
|
||||
|
||||
这对电子邮件链接也有效：contact@example.com。
|
||||
@ -1,214 +0,0 @@
|
||||
---
|
||||
title: What is Mkdirs?
|
||||
description: Mkdirs is the best boilerplate for building directory websites.
|
||||
image: /images/blog/mkdirs-og.png
|
||||
date: 2024-11-25T12:00:00.000Z
|
||||
published: true
|
||||
categories: [news, company]
|
||||
author: mkdirs
|
||||
---
|
||||
|
||||
Until now, trying to style an article, document, or blog post with Tailwind has been a tedious task that required a keen eye for typography and a lot of complex custom CSS.
|
||||
|
||||
By default, Tailwind removes all of the default browser styling from paragraphs, headings, lists and more. This ends up being really useful for building application UIs because you spend less time undoing user-agent styles, but when you _really are_ just trying to style some content that came from a rich-text editor in a CMS or a markdown file, it can be surprising and unintuitive.
|
||||
|
||||
We get lots of complaints about it actually, with people regularly asking us things like:
|
||||
|
||||
> Why is Tailwind removing the default styles on my `h1` elements? How do I disable this? What do you mean I lose all the other base styles too?
|
||||
> We hear you, but we're not convinced that simply disabling our base styles is what you really want. You don't want to have to remove annoying margins every time you use a `p` element in a piece of your dashboard UI. And I doubt you really want your blog posts to use the user-agent styles either — you want them to look _awesome_, not awful.
|
||||
|
||||
The `@tailwindcss/typography` plugin is our attempt to give you what you _actually_ want, without any of the downsides of doing something stupid like disabling our base styles.
|
||||
|
||||
It adds a new `prose` class that you can slap on any block of vanilla HTML content and turn it into a beautiful, well-formatted document:
|
||||
|
||||
```html
|
||||
<article class="prose">
|
||||
<h1>Garlic bread with cheese: What the science tells us</h1>
|
||||
<p>
|
||||
For years parents have espoused the health benefits of eating garlic bread
|
||||
with cheese to their children, with the food earning such an iconic status
|
||||
in our culture that kids will often dress up as warm, cheesy loaf for
|
||||
Halloween.
|
||||
</p>
|
||||
<p>
|
||||
But a recent study shows that the celebrated appetizer may be linked to a
|
||||
series of rabies cases springing up around the country.
|
||||
</p>
|
||||
</article>
|
||||
```
|
||||
|
||||
For more information about how to use the plugin and the features it includes, [read the documentation](https://github.com/tailwindcss/typography/blob/master/README.md).
|
||||
|
||||
---
|
||||
|
||||
## What to expect from here on out
|
||||
|
||||
What follows from here is just a bunch of absolute nonsense I've written to dogfood the plugin itself. It includes every sensible typographic element I could think of, like **bold text**, unordered lists, ordered lists, code blocks, block quotes, _and even italics_.
|
||||
|
||||
It's important to cover all of these use cases for a few reasons:
|
||||
|
||||
1. We want everything to look good out of the box.
|
||||
2. Really just the first reason, that's the whole point of the plugin.
|
||||
3. Here's a third pretend reason though a list with three items looks more realistic than a list with two items.
|
||||
|
||||
Now we're going to try out another header style.
|
||||
|
||||
### Typography should be easy
|
||||
|
||||
So that's a header for you — with any luck if we've done our job correctly that will look pretty reasonable.
|
||||
|
||||
Something a wise person once told me about typography is:
|
||||
|
||||
> Typography is pretty important if you don't want your stuff to look like trash. Make it good then it won't be bad.
|
||||
|
||||
It's probably important that images look okay here by default as well:
|
||||
|
||||
<img
|
||||
src="/images/blog/mksaas-og.png"
|
||||
width="718"
|
||||
height="404"
|
||||
alt="Image"
|
||||
/>
|
||||
|
||||
Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old.
|
||||
|
||||
Now I'm going to show you an example of an unordered list to make sure that looks good, too:
|
||||
|
||||
- So here is the first item in this list.
|
||||
- In this example we're keeping the items short.
|
||||
- Later, we'll use longer, more complex list items.
|
||||
|
||||
And that's the end of this section.
|
||||
|
||||
## What if we stack headings?
|
||||
|
||||
### We should make sure that looks good, too.
|
||||
|
||||
Sometimes you have headings directly underneath each other. In those cases you often have to undo the top margin on the second heading because it usually looks better for the headings to be closer together than a paragraph followed by a heading should be.
|
||||
|
||||
### When a heading comes after a paragraph …
|
||||
|
||||
When a heading comes after a paragraph, we need a bit more space, like I already mentioned above. Now let's see what a more complex list would look like.
|
||||
|
||||
- **I often do this thing where list items have headings.**
|
||||
|
||||
For some reason I think this looks cool which is unfortunate because it's pretty annoying to get the styles right.
|
||||
|
||||
I often have two or three paragraphs in these list items, too, so the hard part is getting the spacing between the paragraphs, list item heading, and separate list items to all make sense. Pretty tough honestly, you could make a strong argument that you just shouldn't write this way.
|
||||
|
||||
- **Since this is a list, I need at least two items.**
|
||||
|
||||
I explained what I'm doing already in the previous list item, but a list wouldn't be a list if it only had one item, and we really want this to look realistic. That's why I've added this second list item so I actually have something to look at when writing the styles.
|
||||
|
||||
- **It's not a bad idea to add a third item either.**
|
||||
|
||||
I think it probably would've been fine to just use two items but three is definitely not worse, and since I seem to be having no trouble making up arbitrary things to type, I might as well include it.
|
||||
|
||||
After this sort of list I usually have a closing statement or paragraph, because it kinda looks weird jumping right to a heading.
|
||||
|
||||
## Code should look okay by default.
|
||||
|
||||
I think most people are going to use [highlight.js](https://highlightjs.org/) or [Prism](https://prismjs.com/) or something if they want to style their code blocks but it wouldn't hurt to make them look _okay_ out of the box, even with no syntax highlighting.
|
||||
|
||||
Here's what a default `tailwind.config.js` file looks like at the time of writing:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
purge: [],
|
||||
theme: {
|
||||
extend: {},
|
||||
},
|
||||
variants: {},
|
||||
plugins: [],
|
||||
};
|
||||
```
|
||||
|
||||
Hopefully that looks good enough to you.
|
||||
|
||||
### What about nested lists?
|
||||
|
||||
Nested lists basically always look bad which is why editors like Medium don't even let you do it, but I guess since some of you goofballs are going to do it we have to carry the burden of at least making it work.
|
||||
|
||||
1. **Nested lists are rarely a good idea.**
|
||||
- You might feel like you are being really "organized" or something but you are just creating a gross shape on the screen that is hard to read.
|
||||
- Nested navigation in UIs is a bad idea too, keep things as flat as possible.
|
||||
- Nesting tons of folders in your source code is also not helpful.
|
||||
2. **Since we need to have more items, here's another one.**
|
||||
- I'm not sure if we'll bother styling more than two levels deep.
|
||||
- Two is already too much, three is guaranteed to be a bad idea.
|
||||
- If you nest four levels deep you belong in prison.
|
||||
3. **Two items isn't really a list, three is good though.**
|
||||
- Again please don't nest lists if you want people to actually read your content.
|
||||
- Nobody wants to look at this.
|
||||
- I'm upset that we even have to bother styling this.
|
||||
|
||||
The most annoying thing about lists in Markdown is that `<li>` elements aren't given a child `<p>` tag unless there are multiple paragraphs in the list item. That means I have to worry about styling that annoying situation too.
|
||||
|
||||
- **For example, here's another nested list.**
|
||||
|
||||
But this time with a second paragraph.
|
||||
|
||||
- These list items won't have `<p>` tags
|
||||
- Because they are only one line each
|
||||
|
||||
- **But in this second top-level list item, they will.**
|
||||
|
||||
This is especially annoying because of the spacing on this paragraph.
|
||||
|
||||
- As you can see here, because I've added a second line, this list item now has a `<p>` tag.
|
||||
|
||||
This is the second line I'm talking about by the way.
|
||||
|
||||
- Finally here's another list item so it's more like a list.
|
||||
|
||||
- A closing list item, but with no nested list, because why not?
|
||||
|
||||
And finally a sentence to close off this section.
|
||||
|
||||
## There are other elements we need to style
|
||||
|
||||
I almost forgot to mention links, like [this link to the Tailwind CSS website](https://tailwindcss.com). We almost made them blue but that's so yesterday, so we went with dark gray, feels edgier.
|
||||
|
||||
We even included table styles, check it out:
|
||||
|
||||
| Wrestler | Origin | Finisher |
|
||||
| ----------------------- | ------------ | ------------------ |
|
||||
| Bret "The Hitman" Hart | Calgary, AB | Sharpshooter |
|
||||
| Stone Cold Steve Austin | Austin, TX | Stone Cold Stunner |
|
||||
| Randy Savage | Sarasota, FL | Elbow Drop |
|
||||
| Vader | Boulder, CO | Vader Bomb |
|
||||
| Razor Ramon | Chuluota, FL | Razor's Edge |
|
||||
|
||||
We also need to make sure inline code looks good, like if I wanted to talk about `<span>` elements or tell you the good news about `@tailwindcss/typography`.
|
||||
|
||||
### Sometimes I even use `code` in headings
|
||||
|
||||
Even though it's probably a bad idea, and historically I've had a hard time making it look good. This _"wrap the code blocks in backticks"_ trick works pretty well though really.
|
||||
|
||||
Another thing I've done in the past is put a `code` tag inside of a link, like if I wanted to tell you about the [`tailwindcss/docs`](https://github.com/tailwindcss/docs) repository. I don't love that there is an underline below the backticks but it is absolutely not worth the madness it would require to avoid it.
|
||||
|
||||
#### We haven't used an `h4` yet
|
||||
|
||||
But now we have. Please don't use `h5` or `h6` in your content, Medium only supports two heading levels for a reason, you animals. I honestly considered using a `before` pseudo-element to scream at you if you use an `h5` or `h6`.
|
||||
|
||||
We don't style them at all out of the box because `h4` elements are already so small that they are the same size as the body copy. What are we supposed to do with an `h5`, make it _smaller_ than the body copy? No thanks.
|
||||
|
||||
### We still need to think about stacked headings though.
|
||||
|
||||
#### Let's make sure we don't screw that up with `h4` elements, either.
|
||||
|
||||
Phew, with any luck we have styled the headings above this text and they look pretty good.
|
||||
|
||||
Let's add a closing paragraph here so things end with a decently sized block of text. I can't explain why I want things to end that way but I have to assume it's because I think things will look weird or unbalanced if there is a heading too close to the end of the document.
|
||||
|
||||
What I've written here is probably long enough, but adding this final sentence can't hurt.
|
||||
|
||||
## GitHub Flavored Markdown
|
||||
|
||||
I've also added support for GitHub Flavored Mardown using `remark-gfm`.
|
||||
|
||||
With `remark-gfm`, we get a few extra features in our markdown. Example: autolink literals.
|
||||
|
||||
A link like www.example.com or https://example.com would automatically be converted into an `a` tag.
|
||||
|
||||
This works for email links too: contact@example.com.
|
||||
@ -1,215 +0,0 @@
|
||||
---
|
||||
title: Mkdirs 是什么？
|
||||
description: Mkdirs 是构建导航站的最佳代码模板。
|
||||
image: /images/blog/mkdirs-og.png
|
||||
date: 2024-11-25T12:00:00.000Z
|
||||
published: true
|
||||
categories: [news, company]
|
||||
author: mkdirs
|
||||
locale: zh
|
||||
---
|
||||
|
||||
到目前为止，尝试使用 Tailwind 来设计文章、文档或博客文章的样式一直是一项繁琐的任务，需要对排版有敏锐的眼光，并且需要大量复杂的自定义 CSS。
|
||||
|
||||
默认情况下，Tailwind 会删除段落、标题、列表等所有默认的浏览器样式。这对于构建应用程序 UI 非常有用，因为您花更少的时间撤销用户代理样式，但是当您真的只是尝试设置来自 CMS 中富文本编辑器或 markdown 文件的内容的样式时，这可能会令人惊讶和不直观。
|
||||
|
||||
我们实际上收到了很多关于它的投诉，人们经常问我们这样的问题：
|
||||
|
||||
> 为什么 Tailwind 删除了我的 `h1` 元素上的默认样式？我如何禁用这个？你说我也会失去所有其他基本样式是什么意思？
|
||||
> 我们听到了您的声音，但我们并不确信简单地禁用我们的基本样式就是您真正想要的。您不希望每次在仪表板 UI 的一部分中使用 `p` 元素时都必须删除烦人的边距。而且我怀疑您真的希望您的博客文章使用用户代理样式——您希望它们看起来很棒，而不是糟糕。
|
||||
|
||||
`@tailwindcss/typography` 插件是我们尝试给您真正想要的东西，而不会有做一些愚蠢的事情（比如禁用我们的基本样式）的任何缺点。
|
||||
|
||||
它添加了一个新的 `prose` 类，您可以将其应用于任何普通 HTML 内容块，并将其转变为一个美丽、格式良好的文档：
|
||||
|
||||
```html
|
||||
<article class="prose">
|
||||
<h1>Garlic bread with cheese: What the science tells us</h1>
|
||||
<p>
|
||||
For years parents have espoused the health benefits of eating garlic bread
|
||||
with cheese to their children, with the food earning such an iconic status
|
||||
in our culture that kids will often dress up as warm, cheesy loaf for
|
||||
Halloween.
|
||||
</p>
|
||||
<p>
|
||||
But a recent study shows that the celebrated appetizer may be linked to a
|
||||
series of rabies cases springing up around the country.
|
||||
</p>
|
||||
</article>
|
||||
```
|
||||
|
||||
有关如何使用该插件及其包含的功能的更多信息，[阅读文档](https://github.com/tailwindcss/typography/blob/master/README.md)。
|
||||
|
||||
---
|
||||
|
||||
## 从现在开始期待什么
|
||||
|
||||
从这里开始的是我写的一堆绝对无意义的内容，用来测试插件本身。它包括我能想到的每一个合理的排版元素，如**粗体文本**、无序列表、有序列表、代码块、块引用，_甚至斜体_。
|
||||
|
||||
涵盖所有这些用例很重要，原因如下：
|
||||
|
||||
1. 我们希望一切开箱即用看起来都很好。
|
||||
2. 实际上只是第一个原因，这是插件的全部意义。
|
||||
3. 这里有第三个假装的原因，尽管一个有三个项目的列表看起来比一个有两个项目的列表更真实。
|
||||
|
||||
现在我们将尝试另一种标题样式。
|
||||
|
||||
### 排版应该很简单
|
||||
|
||||
所以这是给你的一个标题——如果我们做得正确，那应该看起来相当合理。
|
||||
|
||||
一位智者曾经告诉我关于排版的一件事是：
|
||||
|
||||
> 如果你不希望你的东西看起来像垃圾，排版是非常重要的。做好它，那么它就不会糟糕。
|
||||
|
||||
默认情况下，图片在这里看起来也应该不错：
|
||||
|
||||
<img
|
||||
src="/images/blog/mksaas-og.png"
|
||||
width="718"
|
||||
height="404"
|
||||
alt="图片"
|
||||
/>
|
||||
|
||||
与普遍的看法相反，Lorem Ipsum 并不是简单的随机文本。它起源于公元前 45 年的一段古典拉丁文学，使其有超过 2000 年的历史。
|
||||
|
||||
现在我将向您展示一个无序列表的例子，以确保它看起来也不错：
|
||||
|
||||
- 所以这是这个列表中的第一项。
|
||||
- 在这个例子中，我们保持项目简短。
|
||||
- 稍后，我们将使用更长、更复杂的列表项。
|
||||
|
||||
这就是本节的结尾。
|
||||
|
||||
## 如果我们堆叠标题怎么办？
|
||||
|
||||
### 我们也应该确保这看起来不错。
|
||||
|
||||
有时候你有直接堆叠在一起的标题。在这些情况下，你通常必须取消第二个标题上的顶部边距，因为标题彼此靠得更近通常看起来比段落后面跟着标题要好。
|
||||
|
||||
### 当标题在段落之后出现时……
|
||||
|
||||
当标题在段落之后出现时，我们需要更多的空间，就像我上面已经提到的那样。现在让我们看看一个更复杂的列表会是什么样子。
|
||||
|
||||
- **我经常做这种事，列表项有标题。**
|
||||
|
||||
由于某种原因，我认为这看起来很酷，这很不幸，因为要让样式正确是相当烦人的。
|
||||
|
||||
我在这些列表项中通常也有两到三个段落，所以困难的部分是让段落之间的间距、列表项标题和单独的列表项都有意义。老实说，这很困难，你可以提出一个强有力的论点，认为你根本不应该这样写。
|
||||
|
||||
- **由于这是一个列表，我至少需要两个项目。**
|
||||
|
||||
我已经在前面的列表项中解释了我在做什么，但是如果一个列表只有一个项目，那就不是一个列表，我们真的希望这看起来真实。这就是为什么我添加了这第二个列表项，所以我在写样式时实际上有东西可以看。
|
||||
|
||||
- **添加第三项也不是一个坏主意。**
|
||||
|
||||
我认为只使用两个项目可能已经足够了，但三个肯定不会更糟，而且由于我似乎在编造任意的东西时没有遇到麻烦，我不妨包括它。
|
||||
|
||||
在这种列表之后，我通常会有一个结束语或段落，因为直接跳到标题看起来有点奇怪。
|
||||
|
||||
## 代码默认应该看起来不错。
|
||||
|
||||
我认为大多数人如果想要设置他们的代码块的样式，会使用 [highlight.js](https://highlightjs.org/) 或 [Prism](https://prismjs.com/) 或其他东西，但是让它们开箱即用看起来_还不错_，即使没有语法高亮，也不会有害。
|
||||
|
||||
以下是撰写本文时默认的 `tailwind.config.js` 文件的样子：
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
purge: [],
|
||||
theme: {
|
||||
extend: {},
|
||||
},
|
||||
variants: {},
|
||||
plugins: [],
|
||||
};
|
||||
```
|
||||
|
||||
希望这对你来说看起来足够好。
|
||||
|
||||
### 嵌套列表怎么办？
|
||||
|
||||
嵌套列表基本上总是看起来很糟糕，这就是为什么像 Medium 这样的编辑器甚至不让你这样做，但我猜既然你们中的一些傻瓜要这样做，我们至少要承担让它工作的负担。
|
||||
|
||||
1. **嵌套列表很少是一个好主意。**
|
||||
- 你可能觉得你真的很"有组织"或者什么的，但你只是在屏幕上创建一个难以阅读的粗糙形状。
|
||||
- UI 中的嵌套导航也是一个坏主意，尽可能保持扁平。
|
||||
- 在源代码中嵌套大量文件夹也没有帮助。
|
||||
2. **既然我们需要有更多的项目，这里有另一个。**
|
||||
- 我不确定我们是否会费心设置超过两级深度的样式。
|
||||
- 两级已经太多了，三级肯定是一个坏主意。
|
||||
- 如果你嵌套四级深度，你应该进监狱。
|
||||
3. **两个项目并不是真正的列表，三个项目就好了。**
|
||||
- 再次请不要嵌套列表，如果你希望人们真正阅读你的内容。
|
||||
- 没有人想看这个。
|
||||
- 我很不高兴我们甚至必须费心设置这个样式。
|
||||
|
||||
Markdown 中列表最烦人的事情是，除非列表项中有多个段落，否则 `<li>` 元素不会被赋予子 `<p>` 标签。这意味着我也必须担心设置那种烦人情况的样式。
|
||||
|
||||
- **例如，这里是另一个嵌套列表。**
|
||||
|
||||
但这次有第二段。
|
||||
|
||||
- 这些列表项不会有 `<p>` 标签
|
||||
- 因为它们每个只有一行
|
||||
|
||||
- **但在这第二个顶级列表项中，它们会有。**
|
||||
|
||||
这特别烦人，因为这段话的间距。
|
||||
|
||||
- 正如你在这里看到的，因为我添加了第二行，这个列表项现在有一个 `<p>` 标签。
|
||||
|
||||
顺便说一下，这是我说的第二行。
|
||||
|
||||
- 最后这里有另一个列表项，所以它更像一个列表。
|
||||
|
||||
- 一个结束列表项，但没有嵌套列表，为什么不呢？
|
||||
|
||||
最后一句话结束这一节。
|
||||
|
||||
## 还有其他我们需要设置样式的元素
|
||||
|
||||
我几乎忘了提到链接，比如[这个链接到 Tailwind CSS 网站](https://tailwindcss.com)。我们几乎把它们变成蓝色，但那是昨天的事了，所以我们选择了深灰色，感觉更前卫。
|
||||
|
||||
我们甚至包括了表格样式，看看：
|
||||
|
||||
| 摔跤手 | 出生地 | 终结技 |
|
||||
| ----------------------- | ------------- | ------------------- |
|
||||
| Bret "The Hitman" Hart | Calgary, AB | Sharpshooter |
|
||||
| Stone Cold Steve Austin | Austin, TX | Stone Cold Stunner |
|
||||
| Randy Savage | Sarasota, FL | Elbow Drop |
|
||||
| Vader | Boulder, CO | Vader Bomb |
|
||||
| Razor Ramon | Chuluota, FL | Razor's Edge |
|
||||
|
||||
我们还需要确保内联代码看起来不错，比如如果我想谈论 `<span>` 元素或者告诉你关于 `@tailwindcss/typography` 的好消息。
|
||||
|
||||
### 有时我甚至在标题中使用 `code`
|
||||
|
||||
尽管这可能是一个坏主意，而且历史上我一直很难让它看起来不错。不过这个_"将代码块包裹在反引号中"_的技巧效果相当不错。
|
||||
|
||||
我过去做过的另一件事是在链接中放置一个 `code` 标签，比如如果我想告诉你关于 [`tailwindcss/docs`](https://github.com/tailwindcss/docs) 仓库的事情。我不喜欢反引号下面有下划线，但为了避免它而导致的疯狂绝对不值得。
|
||||
|
||||
#### 我们还没有使用 `h4`
|
||||
|
||||
但现在我们有了。请不要在你的内容中使用 `h5` 或 `h6`，Medium 只支持两个标题级别是有原因的，你们这些动物。我老实说考虑过使用 `before` 伪元素，如果你使用 `h5` 或 `h6` 就对你大喊大叫。
|
||||
|
||||
我们根本不会为它们设置样式，因为 `h4` 元素已经很小，与正文大小相同。我们应该怎么处理 `h5`，让它比正文更_小_？不，谢谢。
|
||||
|
||||
### 不过我们仍然需要考虑堆叠的标题。
|
||||
|
||||
#### 让我们确保我们也不会用 `h4` 元素搞砸这个。
|
||||
|
||||
呼，运气好的话，我们已经设置了上面这段文字的标题样式，它们看起来相当不错。
|
||||
|
||||
让我们在这里添加一个结束段落，这样事情就会以一个相当大小的文本块结束。我无法解释为什么我希望事情以这种方式结束，但我必须假设这是因为我认为如果文档末尾太靠近标题，事情会看起来奇怪或不平衡。
|
||||
|
||||
我在这里写的可能已经足够长了，但添加这最后一句话不会有害。
|
||||
|
||||
## GitHub 风格的 Markdown
|
||||
|
||||
我还添加了对使用 `remark-gfm` 的 GitHub 风格 Markdown 的支持。
|
||||
|
||||
使用 `remark-gfm`，我们在 markdown 中获得了一些额外的功能。例如：自动链接文字。
|
||||
|
||||
像 www.example.com 或 https://example.com 这样的链接会自动转换为 `a` 标签。
|
||||
|
||||
这对电子邮件链接也有效：contact@example.com。
|
||||
@ -1,215 +0,0 @@
|
||||
---
|
||||
title: What is MkSaaS?
|
||||
description: MkSaaS is the best boilerplate for building AI SaaS websites.
|
||||
image: /images/blog/mksaas-og.png
|
||||
date: 2024-11-26T12:00:00.000Z
|
||||
published: true
|
||||
categories: [company, product]
|
||||
author: mksaas
|
||||
locale: en
|
||||
---
|
||||
|
||||
Until now, trying to style an article, document, or blog post with Tailwind has been a tedious task that required a keen eye for typography and a lot of complex custom CSS.
|
||||
|
||||
By default, Tailwind removes all of the default browser styling from paragraphs, headings, lists and more. This ends up being really useful for building application UIs because you spend less time undoing user-agent styles, but when you _really are_ just trying to style some content that came from a rich-text editor in a CMS or a markdown file, it can be surprising and unintuitive.
|
||||
|
||||
We get lots of complaints about it actually, with people regularly asking us things like:
|
||||
|
||||
> Why is Tailwind removing the default styles on my `h1` elements? How do I disable this? What do you mean I lose all the other base styles too?
|
||||
> We hear you, but we're not convinced that simply disabling our base styles is what you really want. You don't want to have to remove annoying margins every time you use a `p` element in a piece of your dashboard UI. And I doubt you really want your blog posts to use the user-agent styles either — you want them to look _awesome_, not awful.
|
||||
|
||||
The `@tailwindcss/typography` plugin is our attempt to give you what you _actually_ want, without any of the downsides of doing something stupid like disabling our base styles.
|
||||
|
||||
It adds a new `prose` class that you can slap on any block of vanilla HTML content and turn it into a beautiful, well-formatted document:
|
||||
|
||||
```html
|
||||
<article class="prose">
|
||||
<h1>Garlic bread with cheese: What the science tells us</h1>
|
||||
<p>
|
||||
For years parents have espoused the health benefits of eating garlic bread
|
||||
with cheese to their children, with the food earning such an iconic status
|
||||
in our culture that kids will often dress up as warm, cheesy loaf for
|
||||
Halloween.
|
||||
</p>
|
||||
<p>
|
||||
But a recent study shows that the celebrated appetizer may be linked to a
|
||||
series of rabies cases springing up around the country.
|
||||
</p>
|
||||
</article>
|
||||
```
|
||||
|
||||
For more information about how to use the plugin and the features it includes, [read the documentation](https://github.com/tailwindcss/typography/blob/master/README.md).
|
||||
|
||||
---
|
||||
|
||||
## What to expect from here on out
|
||||
|
||||
What follows from here is just a bunch of absolute nonsense I've written to dogfood the plugin itself. It includes every sensible typographic element I could think of, like **bold text**, unordered lists, ordered lists, code blocks, block quotes, _and even italics_.
|
||||
|
||||
It's important to cover all of these use cases for a few reasons:
|
||||
|
||||
1. We want everything to look good out of the box.
|
||||
2. Really just the first reason, that's the whole point of the plugin.
|
||||
3. Here's a third pretend reason though a list with three items looks more realistic than a list with two items.
|
||||
|
||||
Now we're going to try out another header style.
|
||||
|
||||
### Typography should be easy
|
||||
|
||||
So that's a header for you — with any luck if we've done our job correctly that will look pretty reasonable.
|
||||
|
||||
Something a wise person once told me about typography is:
|
||||
|
||||
> Typography is pretty important if you don't want your stuff to look like trash. Make it good then it won't be bad.
|
||||
|
||||
It's probably important that images look okay here by default as well:
|
||||
|
||||
<img
|
||||
src="/images/blog/mksaas-og.png"
|
||||
width="718"
|
||||
height="404"
|
||||
alt="Image"
|
||||
/>
|
||||
|
||||
Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old.
|
||||
|
||||
Now I'm going to show you an example of an unordered list to make sure that looks good, too:
|
||||
|
||||
- So here is the first item in this list.
|
||||
- In this example we're keeping the items short.
|
||||
- Later, we'll use longer, more complex list items.
|
||||
|
||||
And that's the end of this section.
|
||||
|
||||
## What if we stack headings?
|
||||
|
||||
### We should make sure that looks good, too.
|
||||
|
||||
Sometimes you have headings directly underneath each other. In those cases you often have to undo the top margin on the second heading because it usually looks better for the headings to be closer together than a paragraph followed by a heading should be.
|
||||
|
||||
### When a heading comes after a paragraph …
|
||||
|
||||
When a heading comes after a paragraph, we need a bit more space, like I already mentioned above. Now let's see what a more complex list would look like.
|
||||
|
||||
- **I often do this thing where list items have headings.**
|
||||
|
||||
For some reason I think this looks cool which is unfortunate because it's pretty annoying to get the styles right.
|
||||
|
||||
I often have two or three paragraphs in these list items, too, so the hard part is getting the spacing between the paragraphs, list item heading, and separate list items to all make sense. Pretty tough honestly, you could make a strong argument that you just shouldn't write this way.
|
||||
|
||||
- **Since this is a list, I need at least two items.**
|
||||
|
||||
I explained what I'm doing already in the previous list item, but a list wouldn't be a list if it only had one item, and we really want this to look realistic. That's why I've added this second list item so I actually have something to look at when writing the styles.
|
||||
|
||||
- **It's not a bad idea to add a third item either.**
|
||||
|
||||
I think it probably would've been fine to just use two items but three is definitely not worse, and since I seem to be having no trouble making up arbitrary things to type, I might as well include it.
|
||||
|
||||
After this sort of list I usually have a closing statement or paragraph, because it kinda looks weird jumping right to a heading.
|
||||
|
||||
## Code should look okay by default.
|
||||
|
||||
I think most people are going to use [highlight.js](https://highlightjs.org/) or [Prism](https://prismjs.com/) or something if they want to style their code blocks but it wouldn't hurt to make them look _okay_ out of the box, even with no syntax highlighting.
|
||||
|
||||
Here's what a default `tailwind.config.js` file looks like at the time of writing:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
purge: [],
|
||||
theme: {
|
||||
extend: {},
|
||||
},
|
||||
variants: {},
|
||||
plugins: [],
|
||||
};
|
||||
```
|
||||
|
||||
Hopefully that looks good enough to you.
|
||||
|
||||
### What about nested lists?
|
||||
|
||||
Nested lists basically always look bad which is why editors like Medium don't even let you do it, but I guess since some of you goofballs are going to do it we have to carry the burden of at least making it work.
|
||||
|
||||
1. **Nested lists are rarely a good idea.**
|
||||
- You might feel like you are being really "organized" or something but you are just creating a gross shape on the screen that is hard to read.
|
||||
- Nested navigation in UIs is a bad idea too, keep things as flat as possible.
|
||||
- Nesting tons of folders in your source code is also not helpful.
|
||||
2. **Since we need to have more items, here's another one.**
|
||||
- I'm not sure if we'll bother styling more than two levels deep.
|
||||
- Two is already too much, three is guaranteed to be a bad idea.
|
||||
- If you nest four levels deep you belong in prison.
|
||||
3. **Two items isn't really a list, three is good though.**
|
||||
- Again please don't nest lists if you want people to actually read your content.
|
||||
- Nobody wants to look at this.
|
||||
- I'm upset that we even have to bother styling this.
|
||||
|
||||
The most annoying thing about lists in Markdown is that `<li>` elements aren't given a child `<p>` tag unless there are multiple paragraphs in the list item. That means I have to worry about styling that annoying situation too.
|
||||
|
||||
- **For example, here's another nested list.**
|
||||
|
||||
But this time with a second paragraph.
|
||||
|
||||
- These list items won't have `<p>` tags
|
||||
- Because they are only one line each
|
||||
|
||||
- **But in this second top-level list item, they will.**
|
||||
|
||||
This is especially annoying because of the spacing on this paragraph.
|
||||
|
||||
- As you can see here, because I've added a second line, this list item now has a `<p>` tag.
|
||||
|
||||
This is the second line I'm talking about by the way.
|
||||
|
||||
- Finally here's another list item so it's more like a list.
|
||||
|
||||
- A closing list item, but with no nested list, because why not?
|
||||
|
||||
And finally a sentence to close off this section.
|
||||
|
||||
## There are other elements we need to style
|
||||
|
||||
I almost forgot to mention links, like [this link to the Tailwind CSS website](https://tailwindcss.com). We almost made them blue but that's so yesterday, so we went with dark gray, feels edgier.
|
||||
|
||||
We even included table styles, check it out:
|
||||
|
||||
| Wrestler | Origin | Finisher |
|
||||
| ----------------------- | ------------ | ------------------ |
|
||||
| Bret "The Hitman" Hart | Calgary, AB | Sharpshooter |
|
||||
| Stone Cold Steve Austin | Austin, TX | Stone Cold Stunner |
|
||||
| Randy Savage | Sarasota, FL | Elbow Drop |
|
||||
| Vader | Boulder, CO | Vader Bomb |
|
||||
| Razor Ramon | Chuluota, FL | Razor's Edge |
|
||||
|
||||
We also need to make sure inline code looks good, like if I wanted to talk about `<span>` elements or tell you the good news about `@tailwindcss/typography`.
|
||||
|
||||
### Sometimes I even use `code` in headings
|
||||
|
||||
Even though it's probably a bad idea, and historically I've had a hard time making it look good. This _"wrap the code blocks in backticks"_ trick works pretty well though really.
|
||||
|
||||
Another thing I've done in the past is put a `code` tag inside of a link, like if I wanted to tell you about the [`tailwindcss/docs`](https://github.com/tailwindcss/docs) repository. I don't love that there is an underline below the backticks but it is absolutely not worth the madness it would require to avoid it.
|
||||
|
||||
#### We haven't used an `h4` yet
|
||||
|
||||
But now we have. Please don't use `h5` or `h6` in your content, Medium only supports two heading levels for a reason, you animals. I honestly considered using a `before` pseudo-element to scream at you if you use an `h5` or `h6`.
|
||||
|
||||
We don't style them at all out of the box because `h4` elements are already so small that they are the same size as the body copy. What are we supposed to do with an `h5`, make it _smaller_ than the body copy? No thanks.
|
||||
|
||||
### We still need to think about stacked headings though.
|
||||
|
||||
#### Let's make sure we don't screw that up with `h4` elements, either.
|
||||
|
||||
Phew, with any luck we have styled the headings above this text and they look pretty good.
|
||||
|
||||
Let's add a closing paragraph here so things end with a decently sized block of text. I can't explain why I want things to end that way but I have to assume it's because I think things will look weird or unbalanced if there is a heading too close to the end of the document.
|
||||
|
||||
What I've written here is probably long enough, but adding this final sentence can't hurt.
|
||||
|
||||
## GitHub Flavored Markdown
|
||||
|
||||
I've also added support for GitHub Flavored Mardown using `remark-gfm`.
|
||||
|
||||
With `remark-gfm`, we get a few extra features in our markdown. Example: autolink literals.
|
||||
|
||||
A link like www.example.com or https://example.com would automatically be converted into an `a` tag.
|
||||
|
||||
This works for email links too: contact@example.com.
|
||||
@ -1,215 +0,0 @@
|
||||
---
|
||||
title: MkSaaS 是什么？
|
||||
description: MkSaaS 是构建 AI SaaS 网站的最佳代码模板。
|
||||
image: /images/blog/mksaas-og.png
|
||||
date: 2024-11-26T12:00:00.000Z
|
||||
published: true
|
||||
categories: [company, product]
|
||||
author: mksaas
|
||||
locale: zh
|
||||
---
|
||||
|
||||
到目前为止，尝试使用 Tailwind 来设计文章、文档或博客文章的样式一直是一项繁琐的任务，需要对排版有敏锐的眼光，并且需要大量复杂的自定义 CSS。
|
||||
|
||||
默认情况下，Tailwind 会删除段落、标题、列表等所有默认的浏览器样式。这对于构建应用程序 UI 非常有用，因为您花更少的时间撤销用户代理样式，但是当您真的只是尝试设置来自 CMS 中富文本编辑器或 markdown 文件的内容的样式时，这可能会令人惊讶和不直观。
|
||||
|
||||
我们实际上收到了很多关于它的投诉，人们经常问我们这样的问题：
|
||||
|
||||
> 为什么 Tailwind 删除了我的 `h1` 元素上的默认样式？我如何禁用这个？你说我也会失去所有其他基本样式是什么意思？
|
||||
> 我们听到了您的声音，但我们并不确信简单地禁用我们的基本样式就是您真正想要的。您不希望每次在仪表板 UI 的一部分中使用 `p` 元素时都必须删除烦人的边距。而且我怀疑您真的希望您的博客文章使用用户代理样式——您希望它们看起来很棒，而不是糟糕。
|
||||
|
||||
`@tailwindcss/typography` 插件是我们尝试给您真正想要的东西，而不会有做一些愚蠢的事情（比如禁用我们的基本样式）的任何缺点。
|
||||
|
||||
它添加了一个新的 `prose` 类，您可以将其应用于任何普通 HTML 内容块，并将其转变为一个美丽、格式良好的文档：
|
||||
|
||||
```html
|
||||
<article class="prose">
|
||||
<h1>Garlic bread with cheese: What the science tells us</h1>
|
||||
<p>
|
||||
For years parents have espoused the health benefits of eating garlic bread
|
||||
with cheese to their children, with the food earning such an iconic status
|
||||
in our culture that kids will often dress up as warm, cheesy loaf for
|
||||
Halloween.
|
||||
</p>
|
||||
<p>
|
||||
But a recent study shows that the celebrated appetizer may be linked to a
|
||||
series of rabies cases springing up around the country.
|
||||
</p>
|
||||
</article>
|
||||
```
|
||||
|
||||
有关如何使用该插件及其包含的功能的更多信息，[阅读文档](https://github.com/tailwindcss/typography/blob/master/README.md)。
|
||||
|
||||
---
|
||||
|
||||
## 从现在开始期待什么
|
||||
|
||||
从这里开始的是我写的一堆绝对无意义的内容，用来测试插件本身。它包括我能想到的每一个合理的排版元素，如**粗体文本**、无序列表、有序列表、代码块、块引用，_甚至斜体_。
|
||||
|
||||
涵盖所有这些用例很重要，原因如下：
|
||||
|
||||
1. 我们希望一切开箱即用看起来都很好。
|
||||
2. 实际上只是第一个原因，这是插件的全部意义。
|
||||
3. 这里有第三个假装的原因，尽管一个有三个项目的列表看起来比一个有两个项目的列表更真实。
|
||||
|
||||
现在我们将尝试另一种标题样式。
|
||||
|
||||
### 排版应该很简单
|
||||
|
||||
所以这是给你的一个标题——如果我们做得正确，那应该看起来相当合理。
|
||||
|
||||
一位智者曾经告诉我关于排版的一件事是：
|
||||
|
||||
> 如果你不希望你的东西看起来像垃圾，排版是非常重要的。做好它，那么它就不会糟糕。
|
||||
|
||||
默认情况下，图片在这里看起来也应该不错：
|
||||
|
||||
<img
|
||||
src="/images/blog/mksaas-og.png"
|
||||
width="718"
|
||||
height="404"
|
||||
alt="image"
|
||||
/>
|
||||
|
||||
与普遍的看法相反，Lorem Ipsum 并不是简单的随机文本。它起源于公元前 45 年的一段古典拉丁文学，使其有超过 2000 年的历史。
|
||||
|
||||
现在我将向您展示一个无序列表的例子，以确保它看起来也不错：
|
||||
|
||||
- 所以这是这个列表中的第一项。
|
||||
- 在这个例子中，我们保持项目简短。
|
||||
- 稍后，我们将使用更长、更复杂的列表项。
|
||||
|
||||
这就是本节的结尾。
|
||||
|
||||
## 如果我们堆叠标题怎么办？
|
||||
|
||||
### 我们也应该确保这看起来不错。
|
||||
|
||||
有时候你有直接堆叠在一起的标题。在这些情况下，你通常必须取消第二个标题上的顶部边距，因为标题彼此靠得更近通常看起来比段落后面跟着标题要好。
|
||||
|
||||
### 当标题在段落之后出现时……
|
||||
|
||||
当标题在段落之后出现时，我们需要更多的空间，就像我上面已经提到的那样。现在让我们看看一个更复杂的列表会是什么样子。
|
||||
|
||||
- **我经常做这种事，列表项有标题。**
|
||||
|
||||
由于某种原因，我认为这看起来很酷，这很不幸，因为要让样式正确是相当烦人的。
|
||||
|
||||
我在这些列表项中通常也有两到三个段落，所以困难的部分是让段落之间的间距、列表项标题和单独的列表项都有意义。老实说，这很困难，你可以提出一个强有力的论点，认为你根本不应该这样写。
|
||||
|
||||
- **由于这是一个列表，我至少需要两个项目。**
|
||||
|
||||
我已经在前面的列表项中解释了我在做什么，但是如果一个列表只有一个项目，那就不是一个列表，我们真的希望这看起来真实。这就是为什么我添加了这第二个列表项，所以我在写样式时实际上有东西可以看。
|
||||
|
||||
- **添加第三项也不是一个坏主意。**
|
||||
|
||||
我认为只使用两个项目可能已经足够了，但三个肯定不会更糟，而且由于我似乎在编造任意的东西时没有遇到麻烦，我不妨包括它。
|
||||
|
||||
在这种列表之后，我通常会有一个结束语或段落，因为直接跳到标题看起来有点奇怪。
|
||||
|
||||
## 代码默认应该看起来不错。
|
||||
|
||||
我认为大多数人如果想要设置他们的代码块的样式，会使用 [highlight.js](https://highlightjs.org/) 或 [Prism](https://prismjs.com/) 或其他东西，但是让它们开箱即用看起来_还不错_，即使没有语法高亮，也不会有害。
|
||||
|
||||
以下是撰写本文时默认的 `tailwind.config.js` 文件的样子：
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
purge: [],
|
||||
theme: {
|
||||
extend: {},
|
||||
},
|
||||
variants: {},
|
||||
plugins: [],
|
||||
};
|
||||
```
|
||||
|
||||
希望这对你来说看起来足够好。
|
||||
|
||||
### 嵌套列表怎么办？
|
||||
|
||||
嵌套列表基本上总是看起来很糟糕，这就是为什么像 Medium 这样的编辑器甚至不让你这样做，但我猜既然你们中的一些傻瓜要这样做，我们至少要承担让它工作的负担。
|
||||
|
||||
1. **嵌套列表很少是一个好主意。**
|
||||
- 你可能觉得你真的很"有组织"或者什么的，但你只是在屏幕上创建一个难以阅读的粗糙形状。
|
||||
- UI 中的嵌套导航也是一个坏主意，尽可能保持扁平。
|
||||
- 在源代码中嵌套大量文件夹也没有帮助。
|
||||
2. **既然我们需要有更多的项目，这里有另一个。**
|
||||
- 我不确定我们是否会费心设置超过两级深度的样式。
|
||||
- 两级已经太多了，三级肯定是一个坏主意。
|
||||
- 如果你嵌套四级深度，你应该进监狱。
|
||||
3. **两个项目并不是真正的列表，三个项目就好了。**
|
||||
- 再次请不要嵌套列表，如果你希望人们真正阅读你的内容。
|
||||
- 没有人想看这个。
|
||||
- 我很不高兴我们甚至必须费心设置这个样式。
|
||||
|
||||
Markdown 中列表最烦人的事情是，除非列表项中有多个段落，否则 `<li>` 元素不会被赋予子 `<p>` 标签。这意味着我也必须担心设置那种烦人情况的样式。
|
||||
|
||||
- **例如，这里是另一个嵌套列表。**
|
||||
|
||||
但这次有第二段。
|
||||
|
||||
- 这些列表项不会有 `<p>` 标签
|
||||
- 因为它们每个只有一行
|
||||
|
||||
- **但在这第二个顶级列表项中，它们会有。**
|
||||
|
||||
这特别烦人，因为这段话的间距。
|
||||
|
||||
- 正如你在这里看到的，因为我添加了第二行，这个列表项现在有一个 `<p>` 标签。
|
||||
|
||||
顺便说一下，这是我说的第二行。
|
||||
|
||||
- 最后这里有另一个列表项，所以它更像一个列表。
|
||||
|
||||
- 一个结束列表项，但没有嵌套列表，为什么不呢？
|
||||
|
||||
最后一句话结束这一节。
|
||||
|
||||
## 还有其他我们需要设置样式的元素
|
||||
|
||||
我几乎忘了提到链接，比如[这个链接到 Tailwind CSS 网站](https://tailwindcss.com)。我们几乎把它们变成蓝色，但那是昨天的事了，所以我们选择了深灰色，感觉更前卫。
|
||||
|
||||
我们甚至包括了表格样式，看看：
|
||||
|
||||
| 摔跤手 | 出生地 | 终结技 |
|
||||
| ----------------------- | ------------- | ------------------- |
|
||||
| Bret "The Hitman" Hart | Calgary, AB | Sharpshooter |
|
||||
| Stone Cold Steve Austin | Austin, TX | Stone Cold Stunner |
|
||||
| Randy Savage | Sarasota, FL | Elbow Drop |
|
||||
| Vader | Boulder, CO | Vader Bomb |
|
||||
| Razor Ramon | Chuluota, FL | Razor's Edge |
|
||||
|
||||
我们还需要确保内联代码看起来不错，比如如果我想谈论 `<span>` 元素或者告诉你关于 `@tailwindcss/typography` 的好消息。
|
||||
|
||||
### 有时我甚至在标题中使用 `code`
|
||||
|
||||
尽管这可能是一个坏主意，而且历史上我一直很难让它看起来不错。不过这个_"将代码块包裹在反引号中"_的技巧效果相当不错。
|
||||
|
||||
我过去做过的另一件事是在链接中放置一个 `code` 标签，比如如果我想告诉你关于 [`tailwindcss/docs`](https://github.com/tailwindcss/docs) 仓库的事情。我不喜欢反引号下面有下划线，但为了避免它而导致的疯狂绝对不值得。
|
||||
|
||||
#### 我们还没有使用 `h4`
|
||||
|
||||
但现在我们有了。请不要在你的内容中使用 `h5` 或 `h6`，Medium 只支持两个标题级别是有原因的，你们这些动物。我老实说考虑过使用 `before` 伪元素，如果你使用 `h5` 或 `h6` 就对你大喊大叫。
|
||||
|
||||
我们根本不会为它们设置样式，因为 `h4` 元素已经很小，与正文大小相同。我们应该怎么处理 `h5`，让它比正文更_小_？不，谢谢。
|
||||
|
||||
### 不过我们仍然需要考虑堆叠的标题。
|
||||
|
||||
#### 让我们确保我们也不会用 `h4` 元素搞砸这个。
|
||||
|
||||
呼，运气好的话，我们已经设置了上面这段文字的标题样式，它们看起来相当不错。
|
||||
|
||||
让我们在这里添加一个结束段落，这样事情就会以一个相当大小的文本块结束。我无法解释为什么我希望事情以这种方式结束，但我必须假设这是因为我认为如果文档末尾太靠近标题，事情会看起来奇怪或不平衡。
|
||||
|
||||
我在这里写的可能已经足够长了，但添加这最后一句话不会有害。
|
||||
|
||||
## GitHub 风格的 Markdown
|
||||
|
||||
我还添加了对使用 `remark-gfm` 的 GitHub 风格 Markdown 的支持。
|
||||
|
||||
使用 `remark-gfm`，我们在 markdown 中获得了一些额外的功能。例如：自动链接文字。
|
||||
|
||||
像 www.example.com 或 https://example.com 这样的链接会自动转换为 `a` 标签。
|
||||
|
||||
这对电子邮件链接也有效：contact@example.com。
|
||||
@ -1,215 +0,0 @@
|
||||
---
|
||||
title: What is OG Generator?
|
||||
description: Generate beautiful Open Graph images with zero effort. Use our free online Open Graph Generator tool to generate open graph meta tags for website or blogs.
|
||||
image: /images/blog/oggenerator-og.png
|
||||
date: 2024-11-20T12:00:00.000Z
|
||||
published: true
|
||||
categories: [company, news]
|
||||
author: oggenerator
|
||||
locale: en
|
||||
---
|
||||
|
||||
Until now, trying to style an article, document, or blog post with Tailwind has been a tedious task that required a keen eye for typography and a lot of complex custom CSS.
|
||||
|
||||
By default, Tailwind removes all of the default browser styling from paragraphs, headings, lists and more. This ends up being really useful for building application UIs because you spend less time undoing user-agent styles, but when you _really are_ just trying to style some content that came from a rich-text editor in a CMS or a markdown file, it can be surprising and unintuitive.
|
||||
|
||||
We get lots of complaints about it actually, with people regularly asking us things like:
|
||||
|
||||
> Why is Tailwind removing the default styles on my `h1` elements? How do I disable this? What do you mean I lose all the other base styles too?
|
||||
> We hear you, but we're not convinced that simply disabling our base styles is what you really want. You don't want to have to remove annoying margins every time you use a `p` element in a piece of your dashboard UI. And I doubt you really want your blog posts to use the user-agent styles either — you want them to look _awesome_, not awful.
|
||||
|
||||
The `@tailwindcss/typography` plugin is our attempt to give you what you _actually_ want, without any of the downsides of doing something stupid like disabling our base styles.
|
||||
|
||||
It adds a new `prose` class that you can slap on any block of vanilla HTML content and turn it into a beautiful, well-formatted document:
|
||||
|
||||
```html
|
||||
<article class="prose">
|
||||
<h1>Garlic bread with cheese: What the science tells us</h1>
|
||||
<p>
|
||||
For years parents have espoused the health benefits of eating garlic bread
|
||||
with cheese to their children, with the food earning such an iconic status
|
||||
in our culture that kids will often dress up as warm, cheesy loaf for
|
||||
Halloween.
|
||||
</p>
|
||||
<p>
|
||||
But a recent study shows that the celebrated appetizer may be linked to a
|
||||
series of rabies cases springing up around the country.
|
||||
</p>
|
||||
</article>
|
||||
```
|
||||
|
||||
For more information about how to use the plugin and the features it includes, [read the documentation](https://github.com/tailwindcss/typography/blob/master/README.md).
|
||||
|
||||
---
|
||||
|
||||
## What to expect from here on out
|
||||
|
||||
What follows from here is just a bunch of absolute nonsense I've written to dogfood the plugin itself. It includes every sensible typographic element I could think of, like **bold text**, unordered lists, ordered lists, code blocks, block quotes, _and even italics_.
|
||||
|
||||
It's important to cover all of these use cases for a few reasons:
|
||||
|
||||
1. We want everything to look good out of the box.
|
||||
2. Really just the first reason, that's the whole point of the plugin.
|
||||
3. Here's a third pretend reason though a list with three items looks more realistic than a list with two items.
|
||||
|
||||
Now we're going to try out another header style.
|
||||
|
||||
### Typography should be easy
|
||||
|
||||
So that's a header for you — with any luck if we've done our job correctly that will look pretty reasonable.
|
||||
|
||||
Something a wise person once told me about typography is:
|
||||
|
||||
> Typography is pretty important if you don't want your stuff to look like trash. Make it good then it won't be bad.
|
||||
|
||||
It's probably important that images look okay here by default as well:
|
||||
|
||||
<img
|
||||
src="/images/blog/mksaas-og.png"
|
||||
width="718"
|
||||
height="404"
|
||||
alt="Image"
|
||||
/>
|
||||
|
||||
Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old.
|
||||
|
||||
Now I'm going to show you an example of an unordered list to make sure that looks good, too:
|
||||
|
||||
- So here is the first item in this list.
|
||||
- In this example we're keeping the items short.
|
||||
- Later, we'll use longer, more complex list items.
|
||||
|
||||
And that's the end of this section.
|
||||
|
||||
## What if we stack headings?
|
||||
|
||||
### We should make sure that looks good, too.
|
||||
|
||||
Sometimes you have headings directly underneath each other. In those cases you often have to undo the top margin on the second heading because it usually looks better for the headings to be closer together than a paragraph followed by a heading should be.
|
||||
|
||||
### When a heading comes after a paragraph …
|
||||
|
||||
When a heading comes after a paragraph, we need a bit more space, like I already mentioned above. Now let's see what a more complex list would look like.
|
||||
|
||||
- **I often do this thing where list items have headings.**
|
||||
|
||||
For some reason I think this looks cool which is unfortunate because it's pretty annoying to get the styles right.
|
||||
|
||||
I often have two or three paragraphs in these list items, too, so the hard part is getting the spacing between the paragraphs, list item heading, and separate list items to all make sense. Pretty tough honestly, you could make a strong argument that you just shouldn't write this way.
|
||||
|
||||
- **Since this is a list, I need at least two items.**
|
||||
|
||||
I explained what I'm doing already in the previous list item, but a list wouldn't be a list if it only had one item, and we really want this to look realistic. That's why I've added this second list item so I actually have something to look at when writing the styles.
|
||||
|
||||
- **It's not a bad idea to add a third item either.**
|
||||
|
||||
I think it probably would've been fine to just use two items but three is definitely not worse, and since I seem to be having no trouble making up arbitrary things to type, I might as well include it.
|
||||
|
||||
After this sort of list I usually have a closing statement or paragraph, because it kinda looks weird jumping right to a heading.
|
||||
|
||||
## Code should look okay by default.
|
||||
|
||||
I think most people are going to use [highlight.js](https://highlightjs.org/) or [Prism](https://prismjs.com/) or something if they want to style their code blocks but it wouldn't hurt to make them look _okay_ out of the box, even with no syntax highlighting.
|
||||
|
||||
Here's what a default `tailwind.config.js` file looks like at the time of writing:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
purge: [],
|
||||
theme: {
|
||||
extend: {},
|
||||
},
|
||||
variants: {},
|
||||
plugins: [],
|
||||
};
|
||||
```
|
||||
|
||||
Hopefully that looks good enough to you.
|
||||
|
||||
### What about nested lists?
|
||||
|
||||
Nested lists basically always look bad which is why editors like Medium don't even let you do it, but I guess since some of you goofballs are going to do it we have to carry the burden of at least making it work.
|
||||
|
||||
1. **Nested lists are rarely a good idea.**
|
||||
- You might feel like you are being really "organized" or something but you are just creating a gross shape on the screen that is hard to read.
|
||||
- Nested navigation in UIs is a bad idea too, keep things as flat as possible.
|
||||
- Nesting tons of folders in your source code is also not helpful.
|
||||
2. **Since we need to have more items, here's another one.**
|
||||
- I'm not sure if we'll bother styling more than two levels deep.
|
||||
- Two is already too much, three is guaranteed to be a bad idea.
|
||||
- If you nest four levels deep you belong in prison.
|
||||
3. **Two items isn't really a list, three is good though.**
|
||||
- Again please don't nest lists if you want people to actually read your content.
|
||||
- Nobody wants to look at this.
|
||||
- I'm upset that we even have to bother styling this.
|
||||
|
||||
The most annoying thing about lists in Markdown is that `<li>` elements aren't given a child `<p>` tag unless there are multiple paragraphs in the list item. That means I have to worry about styling that annoying situation too.
|
||||
|
||||
- **For example, here's another nested list.**
|
||||
|
||||
But this time with a second paragraph.
|
||||
|
||||
- These list items won't have `<p>` tags
|
||||
- Because they are only one line each
|
||||
|
||||
- **But in this second top-level list item, they will.**
|
||||
|
||||
This is especially annoying because of the spacing on this paragraph.
|
||||
|
||||
- As you can see here, because I've added a second line, this list item now has a `<p>` tag.
|
||||
|
||||
This is the second line I'm talking about by the way.
|
||||
|
||||
- Finally here's another list item so it's more like a list.
|
||||
|
||||
- A closing list item, but with no nested list, because why not?
|
||||
|
||||
And finally a sentence to close off this section.
|
||||
|
||||
## There are other elements we need to style
|
||||
|
||||
I almost forgot to mention links, like [this link to the Tailwind CSS website](https://tailwindcss.com). We almost made them blue but that's so yesterday, so we went with dark gray, feels edgier.
|
||||
|
||||
We even included table styles, check it out:
|
||||
|
||||
| Wrestler | Origin | Finisher |
|
||||
| ----------------------- | ------------ | ------------------ |
|
||||
| Bret "The Hitman" Hart | Calgary, AB | Sharpshooter |
|
||||
| Stone Cold Steve Austin | Austin, TX | Stone Cold Stunner |
|
||||
| Randy Savage | Sarasota, FL | Elbow Drop |
|
||||
| Vader | Boulder, CO | Vader Bomb |
|
||||
| Razor Ramon | Chuluota, FL | Razor's Edge |
|
||||
|
||||
We also need to make sure inline code looks good, like if I wanted to talk about `<span>` elements or tell you the good news about `@tailwindcss/typography`.
|
||||
|
||||
### Sometimes I even use `code` in headings
|
||||
|
||||
Even though it's probably a bad idea, and historically I've had a hard time making it look good. This _"wrap the code blocks in backticks"_ trick works pretty well though really.
|
||||
|
||||
Another thing I've done in the past is put a `code` tag inside of a link, like if I wanted to tell you about the [`tailwindcss/docs`](https://github.com/tailwindcss/docs) repository. I don't love that there is an underline below the backticks but it is absolutely not worth the madness it would require to avoid it.
|
||||
|
||||
#### We haven't used an `h4` yet
|
||||
|
||||
But now we have. Please don't use `h5` or `h6` in your content, Medium only supports two heading levels for a reason, you animals. I honestly considered using a `before` pseudo-element to scream at you if you use an `h5` or `h6`.
|
||||
|
||||
We don't style them at all out of the box because `h4` elements are already so small that they are the same size as the body copy. What are we supposed to do with an `h5`, make it _smaller_ than the body copy? No thanks.
|
||||
|
||||
### We still need to think about stacked headings though.
|
||||
|
||||
#### Let's make sure we don't screw that up with `h4` elements, either.
|
||||
|
||||
Phew, with any luck we have styled the headings above this text and they look pretty good.
|
||||
|
||||
Let's add a closing paragraph here so things end with a decently sized block of text. I can't explain why I want things to end that way but I have to assume it's because I think things will look weird or unbalanced if there is a heading too close to the end of the document.
|
||||
|
||||
What I've written here is probably long enough, but adding this final sentence can't hurt.
|
||||
|
||||
## GitHub Flavored Markdown
|
||||
|
||||
I've also added support for GitHub Flavored Mardown using `remark-gfm`.
|
||||
|
||||
With `remark-gfm`, we get a few extra features in our markdown. Example: autolink literals.
|
||||
|
||||
A link like www.example.com or https://example.com would automatically be converted into an `a` tag.
|
||||
|
||||
This works for email links too: contact@example.com.
|
||||
@ -1,215 +0,0 @@
|
||||
---
|
||||
title: OG Generator 是什么？
|
||||
description: 免费的在线 Open Graph 图像生成器工具。
|
||||
image: /images/blog/oggenerator-og.png
|
||||
date: 2024-11-20T12:00:00.000Z
|
||||
published: true
|
||||
categories: [company, news]
|
||||
author: oggenerator
|
||||
locale: zh
|
||||
---
|
||||
|
||||
到目前为止，尝试使用 Tailwind 来设计文章、文档或博客文章的样式一直是一项繁琐的任务，需要对排版有敏锐的眼光，并且需要大量复杂的自定义 CSS。
|
||||
|
||||
默认情况下，Tailwind 会删除段落、标题、列表等所有默认的浏览器样式。这对于构建应用程序 UI 非常有用，因为您花更少的时间撤销用户代理样式，但是当您真的只是尝试设置来自 CMS 中富文本编辑器或 markdown 文件的内容的样式时，这可能会令人惊讶和不直观。
|
||||
|
||||
我们实际上收到了很多关于它的投诉，人们经常问我们这样的问题：
|
||||
|
||||
> 为什么 Tailwind 删除了我的 `h1` 元素上的默认样式？我如何禁用这个？你说我也会失去所有其他基本样式是什么意思？
|
||||
> 我们听到了您的声音，但我们并不确信简单地禁用我们的基本样式就是您真正想要的。您不希望每次在仪表板 UI 的一部分中使用 `p` 元素时都必须删除烦人的边距。而且我怀疑您真的希望您的博客文章使用用户代理样式——您希望它们看起来很棒，而不是糟糕。
|
||||
|
||||
`@tailwindcss/typography` 插件是我们尝试给您真正想要的东西，而不会有做一些愚蠢的事情（比如禁用我们的基本样式）的任何缺点。
|
||||
|
||||
它添加了一个新的 `prose` 类，您可以将其应用于任何普通 HTML 内容块，并将其转变为一个美丽、格式良好的文档：
|
||||
|
||||
```html
|
||||
<article class="prose">
|
||||
<h1>Garlic bread with cheese: What the science tells us</h1>
|
||||
<p>
|
||||
For years parents have espoused the health benefits of eating garlic bread
|
||||
with cheese to their children, with the food earning such an iconic status
|
||||
in our culture that kids will often dress up as warm, cheesy loaf for
|
||||
Halloween.
|
||||
</p>
|
||||
<p>
|
||||
But a recent study shows that the celebrated appetizer may be linked to a
|
||||
series of rabies cases springing up around the country.
|
||||
</p>
|
||||
</article>
|
||||
```
|
||||
|
||||
有关如何使用该插件及其包含的功能的更多信息，[阅读文档](https://github.com/tailwindcss/typography/blob/master/README.md)。
|
||||
|
||||
---
|
||||
|
||||
## 从现在开始期待什么
|
||||
|
||||
从这里开始的是我写的一堆绝对无意义的内容，用来测试插件本身。它包括我能想到的每一个合理的排版元素，如**粗体文本**、无序列表、有序列表、代码块、块引用，_甚至斜体_。
|
||||
|
||||
涵盖所有这些用例很重要，原因如下：
|
||||
|
||||
1. 我们希望一切开箱即用看起来都很好。
|
||||
2. 实际上只是第一个原因，这是插件的全部意义。
|
||||
3. 这里有第三个假装的原因，尽管一个有三个项目的列表看起来比一个有两个项目的列表更真实。
|
||||
|
||||
现在我们将尝试另一种标题样式。
|
||||
|
||||
### 排版应该很简单
|
||||
|
||||
所以这是给你的一个标题——如果我们做得正确，那应该看起来相当合理。
|
||||
|
||||
一位智者曾经告诉我关于排版的一件事是：
|
||||
|
||||
> 如果你不希望你的东西看起来像垃圾，排版是非常重要的。做好它，那么它就不会糟糕。
|
||||
|
||||
默认情况下，图片在这里看起来也应该不错：
|
||||
|
||||
<img
|
||||
src="/images/blog/mksaas-og.png"
|
||||
width="718"
|
||||
height="404"
|
||||
alt="图片"
|
||||
/>
|
||||
|
||||
与普遍的看法相反，Lorem Ipsum 并不是简单的随机文本。它起源于公元前 45 年的一段古典拉丁文学，使其有超过 2000 年的历史。
|
||||
|
||||
现在我将向您展示一个无序列表的例子，以确保它看起来也不错：
|
||||
|
||||
- 所以这是这个列表中的第一项。
|
||||
- 在这个例子中，我们保持项目简短。
|
||||
- 稍后，我们将使用更长、更复杂的列表项。
|
||||
|
||||
这就是本节的结尾。
|
||||
|
||||
## 如果我们堆叠标题怎么办？
|
||||
|
||||
### 我们也应该确保这看起来不错。
|
||||
|
||||
有时候你有直接堆叠在一起的标题。在这些情况下，你通常必须取消第二个标题上的顶部边距，因为标题彼此靠得更近通常看起来比段落后面跟着标题要好。
|
||||
|
||||
### 当标题在段落之后出现时……
|
||||
|
||||
当标题在段落之后出现时，我们需要更多的空间，就像我上面已经提到的那样。现在让我们看看一个更复杂的列表会是什么样子。
|
||||
|
||||
- **我经常做这种事，列表项有标题。**
|
||||
|
||||
由于某种原因，我认为这看起来很酷，这很不幸，因为要让样式正确是相当烦人的。
|
||||
|
||||
我在这些列表项中通常也有两到三个段落，所以困难的部分是让段落之间的间距、列表项标题和单独的列表项都有意义。老实说，这很困难，你可以提出一个强有力的论点，认为你根本不应该这样写。
|
||||
|
||||
- **由于这是一个列表，我至少需要两个项目。**
|
||||
|
||||
我已经在前面的列表项中解释了我在做什么，但是如果一个列表只有一个项目，那就不是一个列表，我们真的希望这看起来真实。这就是为什么我添加了这第二个列表项，所以我在写样式时实际上有东西可以看。
|
||||
|
||||
- **添加第三项也不是一个坏主意。**
|
||||
|
||||
我认为只使用两个项目可能已经足够了，但三个肯定不会更糟，而且由于我似乎在编造任意的东西时没有遇到麻烦，我不妨包括它。
|
||||
|
||||
在这种列表之后，我通常会有一个结束语或段落，因为直接跳到标题看起来有点奇怪。
|
||||
|
||||
## 代码默认应该看起来不错。
|
||||
|
||||
我认为大多数人如果想要设置他们的代码块的样式，会使用 [highlight.js](https://highlightjs.org/) 或 [Prism](https://prismjs.com/) 或其他东西，但是让它们开箱即用看起来_还不错_，即使没有语法高亮，也不会有害。
|
||||
|
||||
以下是撰写本文时默认的 `tailwind.config.js` 文件的样子：
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
purge: [],
|
||||
theme: {
|
||||
extend: {},
|
||||
},
|
||||
variants: {},
|
||||
plugins: [],
|
||||
};
|
||||
```
|
||||
|
||||
希望这对你来说看起来足够好。
|
||||
|
||||
### 嵌套列表怎么办？
|
||||
|
||||
嵌套列表基本上总是看起来很糟糕，这就是为什么像 Medium 这样的编辑器甚至不让你这样做，但我猜既然你们中的一些傻瓜要这样做，我们至少要承担让它工作的负担。
|
||||
|
||||
1. **嵌套列表很少是一个好主意。**
|
||||
- 你可能觉得你真的很"有组织"或者什么的，但你只是在屏幕上创建一个难以阅读的粗糙形状。
|
||||
- UI 中的嵌套导航也是一个坏主意，尽可能保持扁平。
|
||||
- 在源代码中嵌套大量文件夹也没有帮助。
|
||||
2. **既然我们需要有更多的项目，这里有另一个。**
|
||||
- 我不确定我们是否会费心设置超过两级深度的样式。
|
||||
- 两级已经太多了，三级肯定是一个坏主意。
|
||||
- 如果你嵌套四级深度，你应该进监狱。
|
||||
3. **两个项目并不是真正的列表，三个项目就好了。**
|
||||
- 再次请不要嵌套列表，如果你希望人们真正阅读你的内容。
|
||||
- 没有人想看这个。
|
||||
- 我很不高兴我们甚至必须费心设置这个样式。
|
||||
|
||||
Markdown 中列表最烦人的事情是，除非列表项中有多个段落，否则 `<li>` 元素不会被赋予子 `<p>` 标签。这意味着我也必须担心设置那种烦人情况的样式。
|
||||
|
||||
- **例如，这里是另一个嵌套列表。**
|
||||
|
||||
但这次有第二段。
|
||||
|
||||
- 这些列表项不会有 `<p>` 标签
|
||||
- 因为它们每个只有一行
|
||||
|
||||
- **但在这第二个顶级列表项中，它们会有。**
|
||||
|
||||
这特别烦人，因为这段话的间距。
|
||||
|
||||
- 正如你在这里看到的，因为我添加了第二行，这个列表项现在有一个 `<p>` 标签。
|
||||
|
||||
顺便说一下，这是我说的第二行。
|
||||
|
||||
- 最后这里有另一个列表项，所以它更像一个列表。
|
||||
|
||||
- 一个结束列表项，但没有嵌套列表，为什么不呢？
|
||||
|
||||
最后一句话结束这一节。
|
||||
|
||||
## 还有其他我们需要设置样式的元素
|
||||
|
||||
我几乎忘了提到链接，比如[这个链接到 Tailwind CSS 网站](https://tailwindcss.com)。我们几乎把它们变成蓝色，但那是昨天的事了，所以我们选择了深灰色，感觉更前卫。
|
||||
|
||||
我们甚至包括了表格样式，看看：
|
||||
|
||||
| 摔跤手 | 出生地 | 终结技 |
|
||||
| ----------------------- | ------------- | ------------------- |
|
||||
| Bret "The Hitman" Hart | Calgary, AB | Sharpshooter |
|
||||
| Stone Cold Steve Austin | Austin, TX | Stone Cold Stunner |
|
||||
| Randy Savage | Sarasota, FL | Elbow Drop |
|
||||
| Vader | Boulder, CO | Vader Bomb |
|
||||
| Razor Ramon | Chuluota, FL | Razor's Edge |
|
||||
|
||||
我们还需要确保内联代码看起来不错，比如如果我想谈论 `<span>` 元素或者告诉你关于 `@tailwindcss/typography` 的好消息。
|
||||
|
||||
### 有时我甚至在标题中使用 `code`
|
||||
|
||||
尽管这可能是一个坏主意，而且历史上我一直很难让它看起来不错。不过这个_"将代码块包裹在反引号中"_的技巧效果相当不错。
|
||||
|
||||
我过去做过的另一件事是在链接中放置一个 `code` 标签，比如如果我想告诉你关于 [`tailwindcss/docs`](https://github.com/tailwindcss/docs) 仓库的事情。我不喜欢反引号下面有下划线，但为了避免它而导致的疯狂绝对不值得。
|
||||
|
||||
#### 我们还没有使用 `h4`
|
||||
|
||||
但现在我们有了。请不要在你的内容中使用 `h5` 或 `h6`，Medium 只支持两个标题级别是有原因的，你们这些动物。我老实说考虑过使用 `before` 伪元素，如果你使用 `h5` 或 `h6` 就对你大喊大叫。
|
||||
|
||||
我们根本不会为它们设置样式，因为 `h4` 元素已经很小，与正文大小相同。我们应该怎么处理 `h5`，让它比正文更_小_？不，谢谢。
|
||||
|
||||
### 不过我们仍然需要考虑堆叠的标题。
|
||||
|
||||
#### 让我们确保我们也不会用 `h4` 元素搞砸这个。
|
||||
|
||||
呼，运气好的话，我们已经设置了上面这段文字的标题样式，它们看起来相当不错。
|
||||
|
||||
让我们在这里添加一个结束段落，这样事情就会以一个相当大小的文本块结束。我无法解释为什么我希望事情以这种方式结束，但我必须假设这是因为我认为如果文档末尾太靠近标题，事情会看起来奇怪或不平衡。
|
||||
|
||||
我在这里写的可能已经足够长了，但添加这最后一句话不会有害。
|
||||
|
||||
## GitHub 风格的 Markdown
|
||||
|
||||
我还添加了对使用 `remark-gfm` 的 GitHub 风格 Markdown 的支持。
|
||||
|
||||
使用 `remark-gfm`，我们在 markdown 中获得了一些额外的功能。例如：自动链接文字。
|
||||
|
||||
像 www.example.com 或 https://example.com 这样的链接会自动转换为 `a` 标签。
|
||||
|
||||
这对电子邮件链接也有效：contact@example.com。
|
||||
@ -16,9 +16,9 @@ description: Support multiple languages in your documentation
|
||||
|
||||
Define the i18n configurations in a file, we will import it with `@/ilb/i18n` in this guide.
|
||||
|
||||
<include cwd meta='title="lib/i18n.ts"'>
|
||||
{/* <include cwd meta='title="lib/i18n.ts"'>
|
||||
../../examples/i18n/lib/i18n.ts
|
||||
</include>
|
||||
</include> */}
|
||||
|
||||
Pass it to the source loader.
|
||||
|
||||
@ -122,7 +122,7 @@ export default async function RootLayout({
|
||||
|
||||
Pass the locale to Fumadocs in your pages and layouts.
|
||||
|
||||
```tsx title="/app/[lang]/(home)/layout.tsx" tab="Home Layout"
|
||||
{/* ```tsx title="/app/[lang]/(home)/layout.tsx" tab="Home Layout"
|
||||
import type { ReactNode } from 'react';
|
||||
import { HomeLayout } from 'fumadocs-ui/layouts/home';
|
||||
import { baseOptions } from '@/app/layout.config';
|
||||
@ -180,7 +180,7 @@ export default async function Page({
|
||||
source.getPages(); // [!code --]
|
||||
source.getPages(lang); // [!code ++]
|
||||
}
|
||||
```
|
||||
``` */}
|
||||
|
||||
### Search
|
||||
|
||||
@ -196,7 +196,7 @@ Configure i18n on your search solution.
|
||||
|
||||
## Writing Documents
|
||||
|
||||
<include>../../shared/page-conventions.i18n.mdx</include>
|
||||
{/* <include>../../shared/page-conventions.i18n.mdx</include> */}
|
||||
|
||||
## Navigation
|
||||
|
||||
|
||||
@ -16,9 +16,9 @@ description: 在您的文档中支持多种语言
|
||||
|
||||
在一个文件中定义 i18n 配置，我们将在本指南中使用 `@/ilb/i18n` 导入它。
|
||||
|
||||
<include cwd meta='title="lib/i18n.ts"'>
|
||||
{/* <include cwd meta='title="lib/i18n.ts"'>
|
||||
../../examples/i18n/lib/i18n.ts
|
||||
</include>
|
||||
</include> */}
|
||||
|
||||
将其传递给源加载器。
|
||||
|
||||
@ -122,7 +122,7 @@ export default async function RootLayout({
|
||||
|
||||
在您的页面和布局中将区域设置传递给 Fumadocs。
|
||||
|
||||
```tsx title="/app/[lang]/(home)/layout.tsx" tab="Home Layout"
|
||||
{/* ```tsx title="/app/[lang]/(home)/layout.tsx" tab="Home Layout"
|
||||
import type { ReactNode } from 'react';
|
||||
import { HomeLayout } from 'fumadocs-ui/layouts/home';
|
||||
import { baseOptions } from '@/app/layout.config';
|
||||
@ -180,7 +180,7 @@ export default async function Page({
|
||||
source.getPages(); // [!code --]
|
||||
source.getPages(lang); // [!code ++]
|
||||
}
|
||||
```
|
||||
``` */}
|
||||
|
||||
### 搜索
|
||||
|
||||
@ -196,7 +196,7 @@ export default async function Page({
|
||||
|
||||
## 编写文档
|
||||
|
||||
<include>../../shared/page-conventions.i18n.mdx</include>
|
||||
{/* <include>../../shared/page-conventions.i18n.mdx</include> */}
|
||||
|
||||
## 导航
|
||||
|
||||
|
||||
@ -13,6 +13,7 @@
|
||||
"static-export",
|
||||
"---Writing---",
|
||||
"markdown",
|
||||
"internationalization",
|
||||
"---UI---",
|
||||
"customisation",
|
||||
"theme",
|
||||
|
||||
@ -13,6 +13,7 @@
|
||||
"static-export",
|
||||
"---写作---",
|
||||
"markdown",
|
||||
"internationalization",
|
||||
"---UI---",
|
||||
"customisation",
|
||||
"theme",
|
||||
|
||||
@ -20,7 +20,7 @@ interface CustomMDXContentProps {
|
||||
* Enhanced MDX Content component that includes commonly used MDX components
|
||||
* It can be used for blog posts, documentation, and custom pages
|
||||
*/
|
||||
export function CustomMDXContent({
|
||||
export async function CustomMDXContent({
|
||||
code,
|
||||
customComponents = {},
|
||||
includeFumadocsComponents = true,
|
||||
@ -28,6 +28,7 @@ export function CustomMDXContent({
|
||||
// Start with default components
|
||||
const baseComponents: Record<string, any> = {
|
||||
...defaultMdxComponents,
|
||||
...((await import('lucide-react')) as unknown as MDXComponents),
|
||||
...customComponents,
|
||||
};
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user