diff --git a/docs/en/guide/doc-page.md b/docs/en/guide/doc-page.md index e52e5c6e..10527a02 100644 --- a/docs/en/guide/doc-page.md +++ b/docs/en/guide/doc-page.md @@ -1 +1,87 @@ # Doc Page + +The Island.js default theme has an built-in doc page.You can configure these part of it by the following ways: + +## Sidebar + +Refer to the left sidebar.You can configure the sidebar in the frontmatter of the body page: + +```md +--- +sidebar: false +--- +``` + +The value of `sidebar` is a boolean value, if `false`, the sidebar will not be shown. + +## Outline + +Outline information will be presented in the right sidebar, you can configure the outline information in the frontmatter of the body page: + +```md +--- +outline: false +--- +``` + +The value of `outline` is a boolean value, if `false`, outline information won't be displayed. + +## Outline title + +You can configure the title of the outline by `themeConfig.outlineTitle`: + +```js +import { defineConfig } from 'islandjs'; + +export default defineConfig({ + themeConfig: { + outlineTitle: 'ON THIS PAGE' + } +}); +``` + +## Prev/Next Page + +You can configure the previous page text by `themeConfig.prevPageText` or `themeConfig.nextPageText`: + +```js +import { defineConfig } from 'islandjs'; + +export default defineConfig({ + themeConfig: { + prevPageText: 'Previous Page', + nextPageText: 'Next Page' + } +}); +``` + +## Edit Link + +You can configure the edit link by `themeConfig.editLink`: + +```js +import { defineConfig } from 'islandjs'; + +export default defineConfig({ + themeConfig: { + editLink: { + text: 'Edit this page on GitHub', + pattern: 'https://github.com/sanyuan0704/island.js/tree/master/docs/:path' + } + } +}); +``` + +## Last Updated Text + +You can configure the last updated text by `themeConfig.lastUpdatedText`: + +```js +import { defineConfig } from 'islandjs'; + +export default defineConfig({ + themeConfig: { + lastUpdatedText: 'Last Updated' + } +}); +``` diff --git a/docs/en/guide/use-mdx.mdx b/docs/en/guide/use-mdx.mdx index 07ae1261..870230c1 100644 --- a/docs/en/guide/use-mdx.mdx +++ b/docs/en/guide/use-mdx.mdx @@ -42,7 +42,7 @@ You can also access the property defined in front matter, for example: title: Hello World --- -# {meta.title} +# {frontmatter.title} ``` The properties defined in front matter will be passed to the component as `meta` property.So the final output will be: diff --git a/docs/zh/guide/doc-page.md b/docs/zh/guide/doc-page.md index 7e349782..77a4367e 100644 --- a/docs/zh/guide/doc-page.md +++ b/docs/zh/guide/doc-page.md @@ -1 +1,87 @@ # 正文页面 + +你可以配置正文页面的侧边栏和大纲信息。 + +## 侧边栏 + +你可以在正文页面的 frontmatter 中配置侧边栏： + +```md +--- +sidebar: false +--- +``` + +`sidebar` 的值为一个布尔值，如果为 `false`，则不会显示侧边栏。 + +## 大纲 + +大纲信息将会呈现在右边的侧栏，你可以在正文页面的 frontmatter 中配置大纲信息： + +```md +--- +outline: false +--- +``` + +`outline` 的值为一个布尔值，如果为 `false`，则不会显示大纲信息。 + +## 大纲标题 + +通过 `themeConfig.outlineTitle` 配置大纲的标题： + +```js +import { defineConfig } from 'islandjs'; + +export default defineConfig({ + themeConfig: { + outlineTitle: 'ON THIS PAGE' + } +}); +``` + +## 上一页/下一页 + +通过 `themeConfig.prevPageText` 或 `themeConfig.nextPageText` 配置上一页/下一页文本： + +```js +import { defineConfig } from 'islandjs'; + +export default defineConfig({ + themeConfig: { + prevPageText: 'Previous Page', + nextPageText: 'Next Page' + } +}); +``` + +## 编辑链接 + +通过 `themeConfig.editLink` 配置编辑链接： + +```js +import { defineConfig } from 'islandjs'; + +export default defineConfig({ + themeConfig: { + editLink: { + text: 'Edit this page on GitHub', + pattern: 'https://github.com/sanyuan0704/island.js/tree/master/docs/:path' + } + } +}); +``` + +## 上次更新 + +通过 `themeConfig.lastUpdatedText` 配置上次更新的显示文本： + +```js +import { defineConfig } from 'islandjs'; + +export default defineConfig({ + themeConfig: { + lastUpdatedText: 'Last Updated' + } +}); +``` diff --git a/docs/zh/guide/home-page.md b/docs/zh/guide/home-page.md index 8b5546c3..34565359 100644 --- a/docs/zh/guide/home-page.md +++ b/docs/zh/guide/home-page.md @@ -47,22 +47,7 @@ export interface HeroAction { } ``` -## features - -`features` 部分是 Home 页面的特性介绍部分，它的配置是一个数组，每个元素有以下类型： - -```ts -export interface Feature { - // Feature 标题 - title: string; - // Feature 详细介绍 - details: string; - // Feature 图标，一般为 emoji - icon: string; -} -``` - -## 完整配置举例 +举个例子: ```md --- @@ -82,16 +67,64 @@ hero: - theme: alt text: View on GitHub link: https://github.com/sanyuan0704/island +--- +``` + +## features + +`features` 部分是 Home 页面的特性介绍部分，它的配置是一个数组，每个元素有以下类型： + +```ts +export interface Feature { + // Feature 标题 + title: string; + // Feature 详细介绍 + details: string; + // Feature 图标，一般为 emoji + icon: string; +} +``` +举个例子: + +```md features: - - title: "Vite: The DX that can't be beat" - details: With Markdown-centered content, it's built to help you focus on writing and deployed with minimum configuration. - icon: 🚀 - - title: 'MDX: The flexible way to write content' - details: MDX is a powerful way to write content. You can use React components in Markdown. - icon: 📦 - - title: 'Islands Arch: The higher performance in production' - details: Designed to be islands architecture, means less javascript bundle, partial hydration and better performance about FCP, TTI. - icon: ✨ ---- + +- title: "Vite: The DX that can't be beat" + details: With Markdown-centered content, it's built to help you focus on writing and deployed with minimum configuration. + icon: 🚀 +- title: 'MDX: The flexible way to write content' + details: MDX is a powerful way to write content. You can use React components in Markdown. + icon: 📦 +- title: 'Islands Arch: The higher performance in production' + details: Designed to be islands architecture, means less javascript bundle, partial hydration and better performance about FCP, TTI. + icon: ✨ +``` + +## 页脚 + +你可以通过 `themeConfig.footer` 来自定义 Home 页面的页脚。它的配置是一个对象，有以下类型： + +```ts +export interface Footer { + // 版权信息(显示在最底部) + copyright?: string; + // 页脚文本 + message?: string; +} +``` + +举个例子: + +```js +import { defineConfig } from 'islandjs'; + +export default defineConfig({ + themeConfig: { + footer: { + message: 'Released under the MIT License.', + copyright: 'Copyright © 2022-present Xingyuan Yang' + } + } +}); ``` diff --git a/docs/zh/guide/use-mdx.mdx b/docs/zh/guide/use-mdx.mdx index a254ae0b..e8f30b19 100644 --- a/docs/zh/guide/use-mdx.mdx +++ b/docs/zh/guide/use-mdx.mdx @@ -46,7 +46,7 @@ title: Hello World title: Hello World --- -# {meta.title} +# {frontmatter.title} ``` 前面定义的属性将作为 `meta` 属性传递给组件。所以最终输出将是： diff --git a/src/node/plugin-mdx/pluginMdxRollup.ts b/src/node/plugin-mdx/pluginMdxRollup.ts index aacf3faa..40c5fdd8 100644 --- a/src/node/plugin-mdx/pluginMdxRollup.ts +++ b/src/node/plugin-mdx/pluginMdxRollup.ts @@ -25,7 +25,7 @@ export async function pluginMdxRollup( remarkPluginGFM, // The following two plugin for frontmatter remarkPluginFrontMatter, - [remarkPluginMDXFrontMatter, { name: 'meta' }], + [remarkPluginMDXFrontMatter, { name: 'frontmatter' }], remarkPluginToc, [ remarkPluginNormalizeLink, diff --git a/src/runtime/app.tsx b/src/runtime/app.tsx index 24fb48fe..a1503695 100644 --- a/src/runtime/app.tsx +++ b/src/runtime/app.tsx @@ -23,7 +23,8 @@ export async function waitForApp(routePath: string): Promise { pagePath, siteData.base ); - const isApiPage = mod?.meta?.api || mod?.meta?.pageType === 'api'; + const isApiPage = + mod?.frontmatter?.api || mod?.frontmatter?.pageType === 'api'; // API Page if (isApiPage) { const subModules = await Promise.all( @@ -56,7 +57,7 @@ export async function waitForApp(routePath: string): Promise { pagePath, relativePagePath, ...omit(mod, ['default']), - pageType: mod?.meta?.pageType || 'doc', + pageType: mod?.frontmatter?.pageType || 'doc', routePath } as PageData; } diff --git a/src/shared/types/index.ts b/src/shared/types/index.ts index 7bae74ef..85faa27a 100644 --- a/src/shared/types/index.ts +++ b/src/shared/types/index.ts @@ -137,7 +137,7 @@ export type ComponentPropsWithIsland = T & { __island?: boolean }; export interface PageModule> { default: T; - meta?: FrontMatterMeta; + frontmatter?: FrontMatterMeta; content?: string; [key: string]: unknown; } @@ -151,6 +151,8 @@ export interface FrontMatterMeta { pageType: PageType; features?: Feature[]; hero?: Hero; + sidebar?: boolean; + outline?: boolean; } export interface PageData { @@ -159,7 +161,7 @@ export interface PageData { relativePagePath: string; lastUpdatedTime?: string; title?: string; - meta?: FrontMatterMeta; + frontmatter?: FrontMatterMeta; description?: string; pageType: PageType; toc?: Header[]; diff --git a/src/theme-default/components/HomeFeatures/index.tsx b/src/theme-default/components/HomeFeatures/index.tsx index 7dc25523..80a13c17 100644 --- a/src/theme-default/components/HomeFeatures/index.tsx +++ b/src/theme-default/components/HomeFeatures/index.tsx @@ -16,8 +16,8 @@ const getGridClass = (count?: number) => { }; export function HomeFeature() { - const { meta } = usePageData(); - const features = meta?.features; + const { frontmatter } = usePageData(); + const features = frontmatter?.features; const gridClass = getGridClass(features?.length); return (
diff --git a/src/theme-default/components/HomeHero/index.tsx b/src/theme-default/components/HomeHero/index.tsx index 55f7ef75..eb8956ba 100644 --- a/src/theme-default/components/HomeHero/index.tsx +++ b/src/theme-default/components/HomeHero/index.tsx @@ -12,8 +12,8 @@ const DEFAULT_HERO = { }; export function HomeHero() { - const { meta } = usePageData(); - const hero = meta?.hero || DEFAULT_HERO; + const { frontmatter } = usePageData(); + const hero = frontmatter?.hero || DEFAULT_HERO; const hasImage = hero.image !== undefined; return ( diff --git a/src/theme-default/layout/Layout/index.tsx b/src/theme-default/layout/Layout/index.tsx index 441f72f3..59d907ca 100644 --- a/src/theme-default/layout/Layout/index.tsx +++ b/src/theme-default/layout/Layout/index.tsx @@ -11,13 +11,13 @@ export const Layout: React.FC = () => { const { // Inject by remark-plugin-toc title: articleTitle, - meta, + frontmatter, siteData, pageType } = usePageData(); // Priority: front matter title > h1 title > site title - const title = (meta?.title ?? articleTitle) || siteData?.title; - const description = meta?.description || siteData.description; + const title = (frontmatter?.title ?? articleTitle) || siteData?.title; + const description = frontmatter?.description || siteData.description; // Use doc layout by default const getContentLayout = () => { switch (pageType) { diff --git a/src/theme-default/logic/search.ts b/src/theme-default/logic/search.ts index b6b38de8..054d65e4 100644 --- a/src/theme-default/logic/search.ts +++ b/src/theme-default/logic/search.ts @@ -57,7 +57,7 @@ export class PageSearcher { ); const pagesForSearch: PageDataForSearch[] = pages .filter((page) => { - return !WHITE_PAGE_TYPES.includes(page.meta?.pageType || ''); + return !WHITE_PAGE_TYPES.includes(page.frontmatter?.pageType || ''); }) .map((page) => ({ title: page.title!,