diff --git a/packages/docusaurus-plugin-content-pages/src/__tests__/__snapshots__/index.test.ts.snap b/packages/docusaurus-plugin-content-pages/src/__tests__/__snapshots__/index.test.ts.snap index fc5fa2196778..bc9b5308c3eb 100644 --- a/packages/docusaurus-plugin-content-pages/src/__tests__/__snapshots__/index.test.ts.snap +++ b/packages/docusaurus-plugin-content-pages/src/__tests__/__snapshots__/index.test.ts.snap @@ -14,9 +14,12 @@ exports[`docusaurus-plugin-content-pages loads simple pages 1`] = ` }, { "description": "Markdown index page", + "editUrl": undefined, "frontMatter": { "custom_frontMatter": "added by parseFrontMatter", }, + "lastUpdatedAt": undefined, + "lastUpdatedBy": undefined, "permalink": "/hello/", "source": "@site/src/pages/hello/index.md", "title": "Index", @@ -25,11 +28,14 @@ exports[`docusaurus-plugin-content-pages loads simple pages 1`] = ` }, { "description": "my MDX page", + "editUrl": undefined, "frontMatter": { "custom_frontMatter": "added by parseFrontMatter", "description": "my MDX page", "title": "MDX page", }, + "lastUpdatedAt": undefined, + "lastUpdatedBy": undefined, "permalink": "/hello/mdxPage", "source": "@site/src/pages/hello/mdxPage.mdx", "title": "MDX page", @@ -43,9 +49,12 @@ exports[`docusaurus-plugin-content-pages loads simple pages 1`] = ` }, { "description": "translated Markdown page", + "editUrl": undefined, "frontMatter": { "custom_frontMatter": "added by parseFrontMatter", }, + "lastUpdatedAt": undefined, + "lastUpdatedBy": undefined, "permalink": "/hello/translatedMd", "source": "@site/src/pages/hello/translatedMd.md", "title": undefined, @@ -74,9 +83,12 @@ exports[`docusaurus-plugin-content-pages loads simple pages with french translat }, { "description": "Markdown index page", + "editUrl": undefined, "frontMatter": { "custom_frontMatter": "added by parseFrontMatter", }, + "lastUpdatedAt": undefined, + "lastUpdatedBy": undefined, "permalink": "/fr/hello/", "source": "@site/src/pages/hello/index.md", "title": "Index", @@ -85,11 +97,14 @@ exports[`docusaurus-plugin-content-pages loads simple pages with french translat }, { "description": "my MDX page", + "editUrl": undefined, "frontMatter": { "custom_frontMatter": "added by parseFrontMatter", "description": "my MDX page", "title": "MDX page", }, + "lastUpdatedAt": undefined, + "lastUpdatedBy": undefined, "permalink": "/fr/hello/mdxPage", "source": "@site/src/pages/hello/mdxPage.mdx", "title": "MDX page", @@ -103,9 +118,12 @@ exports[`docusaurus-plugin-content-pages loads simple pages with french translat }, { "description": "translated Markdown page (fr)", + "editUrl": undefined, "frontMatter": { "custom_frontMatter": "added by parseFrontMatter", }, + "lastUpdatedAt": undefined, + "lastUpdatedBy": undefined, "permalink": "/fr/hello/translatedMd", "source": "@site/i18n/fr/docusaurus-plugin-content-pages/hello/translatedMd.md", "title": undefined, @@ -119,3 +137,72 @@ exports[`docusaurus-plugin-content-pages loads simple pages with french translat }, ] `; + +exports[`docusaurus-plugin-content-pages loads simple pages with last update 1`] = ` +[ + { + "permalink": "/", + "source": "@site/src/pages/index.js", + "type": "jsx", + }, + { + "permalink": "/typescript", + "source": "@site/src/pages/typescript.tsx", + "type": "jsx", + }, + { + "description": "Markdown index page", + "editUrl": "url placeholder", + "frontMatter": { + "custom_frontMatter": "added by parseFrontMatter", + }, + "lastUpdatedAt": 1539502055000, + "lastUpdatedBy": "Author", + "permalink": "/hello/", + "source": "@site/src/pages/hello/index.md", + "title": "Index", + "type": "mdx", + "unlisted": false, + }, + { + "description": "my MDX page", + "editUrl": "url placeholder", + "frontMatter": { + "custom_frontMatter": "added by parseFrontMatter", + "description": "my MDX page", + "title": "MDX page", + }, + "lastUpdatedAt": 1539502055000, + "lastUpdatedBy": "Author", + "permalink": "/hello/mdxPage", + "source": "@site/src/pages/hello/mdxPage.mdx", + "title": "MDX page", + "type": "mdx", + "unlisted": false, + }, + { + "permalink": "/hello/translatedJs", + "source": "@site/src/pages/hello/translatedJs.js", + "type": "jsx", + }, + { + "description": "translated Markdown page", + "editUrl": "url placeholder", + "frontMatter": { + "custom_frontMatter": "added by parseFrontMatter", + }, + "lastUpdatedAt": 1539502055000, + "lastUpdatedBy": "Author", + "permalink": "/hello/translatedMd", + "source": "@site/src/pages/hello/translatedMd.md", + "title": undefined, + "type": "mdx", + "unlisted": false, + }, + { + "permalink": "/hello/world", + "source": "@site/src/pages/hello/world.js", + "type": "jsx", + }, +] +`; diff --git a/packages/docusaurus-plugin-content-pages/src/__tests__/index.test.ts b/packages/docusaurus-plugin-content-pages/src/__tests__/index.test.ts index 5527f11e5ad0..24870c77bccb 100644 --- a/packages/docusaurus-plugin-content-pages/src/__tests__/index.test.ts +++ b/packages/docusaurus-plugin-content-pages/src/__tests__/index.test.ts @@ -46,4 +46,24 @@ describe('docusaurus-plugin-content-pages', () => { expect(pagesMetadata).toMatchSnapshot(); }); + + it('loads simple pages with last update', async () => { + const siteDir = path.join(__dirname, '__fixtures__', 'website'); + const context = await loadContext({siteDir}); + const plugin = pluginContentPages( + context, + validateOptions({ + validate: normalizePluginOptions, + options: { + path: 'src/pages', + editUrl: () => 'url placeholder', + showLastUpdateAuthor: true, + showLastUpdateTime: true, + }, + }), + ); + const pagesMetadata = await plugin.loadContent!(); + + expect(pagesMetadata).toMatchSnapshot(); + }); }); diff --git a/packages/docusaurus-plugin-content-pages/src/frontMatter.ts b/packages/docusaurus-plugin-content-pages/src/frontMatter.ts index b87907adbd5f..5a87b1a221df 100644 --- a/packages/docusaurus-plugin-content-pages/src/frontMatter.ts +++ b/packages/docusaurus-plugin-content-pages/src/frontMatter.ts @@ -11,6 +11,7 @@ import { FrontMatterTOCHeadingLevels, ContentVisibilitySchema, URISchema, + FrontMatterLastUpdateSchema, } from '@docusaurus/utils-validation'; import type {PageFrontMatter} from '@docusaurus/plugin-content-pages'; @@ -24,6 +25,7 @@ const PageFrontMatterSchema = Joi.object({ wrapperClassName: Joi.string(), hide_table_of_contents: Joi.boolean(), ...FrontMatterTOCHeadingLevels, + last_update: FrontMatterLastUpdateSchema, }).concat(ContentVisibilitySchema); export function validatePageFrontMatter(frontMatter: { diff --git a/packages/docusaurus-plugin-content-pages/src/index.ts b/packages/docusaurus-plugin-content-pages/src/index.ts index 7fe81e83af33..6363fa1914c5 100644 --- a/packages/docusaurus-plugin-content-pages/src/index.ts +++ b/packages/docusaurus-plugin-content-pages/src/index.ts @@ -23,6 +23,9 @@ import { parseMarkdownFile, isUnlisted, isDraft, + readLastUpdateData, + getEditUrl, + posixPath, } from '@docusaurus/utils'; import {validatePageFrontMatter} from './frontMatter'; import type {LoadContext, Plugin, RouteMetadata} from '@docusaurus/types'; @@ -45,7 +48,8 @@ export default function pluginContentPages( context: LoadContext, options: PluginOptions, ): Plugin { - const {siteConfig, siteDir, generatedFilesDir, localizationDir} = context; + const {siteConfig, siteDir, generatedFilesDir, localizationDir, i18n} = + context; const contentPaths: PagesContentPaths = { contentPath: path.resolve(siteDir, options.path), @@ -73,7 +77,7 @@ export default function pluginContentPages( }, async loadContent() { - const {include} = options; + const {include, editUrl} = options; if (!(await fs.pathExists(contentPaths.contentPath))) { return null; @@ -120,6 +124,50 @@ export default function pluginContentPages( }); const frontMatter = validatePageFrontMatter(unsafeFrontMatter); + const pagesDirPath = await getFolderContainingFile( + getContentPathList(contentPaths), + relativeSource, + ); + + const pagesSourceAbsolute = path.join(pagesDirPath, relativeSource); + + function getPagesEditUrl() { + const pagesPathRelative = path.relative( + pagesDirPath, + path.resolve(pagesSourceAbsolute), + ); + + if (typeof editUrl === 'function') { + return editUrl({ + pagesDirPath: posixPath(path.relative(siteDir, pagesDirPath)), + pagesPath: posixPath(pagesPathRelative), + permalink, + locale: i18n.currentLocale, + }); + } else if (typeof editUrl === 'string') { + const isLocalized = + pagesDirPath === contentPaths.contentPathLocalized; + const fileContentPath = + isLocalized && options.editLocalizedFiles + ? contentPaths.contentPathLocalized + : contentPaths.contentPath; + + const contentPathEditUrl = normalizeUrl([ + editUrl, + posixPath(path.relative(siteDir, fileContentPath)), + ]); + + return getEditUrl(pagesPathRelative, contentPathEditUrl); + } + return undefined; + } + + const lastUpdatedData = await readLastUpdateData( + source, + options, + frontMatter.last_update, + ); + if (isDraft({frontMatter})) { return undefined; } @@ -132,6 +180,9 @@ export default function pluginContentPages( title: frontMatter.title ?? contentTitle, description: frontMatter.description ?? excerpt, frontMatter, + lastUpdatedBy: lastUpdatedData.lastUpdatedBy, + lastUpdatedAt: lastUpdatedData.lastUpdatedAt, + editUrl: getPagesEditUrl(), unlisted, }; } @@ -160,12 +211,12 @@ export default function pluginContentPages( const {addRoute, createData} = actions; function createPageRouteMetadata(metadata: Metadata): RouteMetadata { + const lastUpdatedAt = + metadata.type === 'mdx' ? metadata.lastUpdatedAt : undefined; + return { sourceFilePath: aliasedSitePathToRelativePath(metadata.source), - // TODO add support for last updated date in the page plugin - // at least for Markdown files - // lastUpdatedAt: metadata.lastUpdatedAt, - lastUpdatedAt: undefined, + lastUpdatedAt, }; } diff --git a/packages/docusaurus-plugin-content-pages/src/options.ts b/packages/docusaurus-plugin-content-pages/src/options.ts index 014f07f11980..88c3201b3008 100644 --- a/packages/docusaurus-plugin-content-pages/src/options.ts +++ b/packages/docusaurus-plugin-content-pages/src/options.ts @@ -11,6 +11,7 @@ import { RehypePluginsSchema, AdmonitionsSchema, RouteBasePathSchema, + URISchema, } from '@docusaurus/utils-validation'; import {GlobExcludeDefault} from '@docusaurus/utils'; import type {OptionValidationContext} from '@docusaurus/types'; @@ -27,6 +28,9 @@ export const DEFAULT_OPTIONS: PluginOptions = { beforeDefaultRehypePlugins: [], beforeDefaultRemarkPlugins: [], admonitions: true, + showLastUpdateTime: false, + showLastUpdateAuthor: false, + editLocalizedFiles: false, }; const PluginOptionSchema = Joi.object({ @@ -44,6 +48,12 @@ const PluginOptionSchema = Joi.object({ DEFAULT_OPTIONS.beforeDefaultRemarkPlugins, ), admonitions: AdmonitionsSchema.default(DEFAULT_OPTIONS.admonitions), + showLastUpdateTime: Joi.bool().default(DEFAULT_OPTIONS.showLastUpdateTime), + showLastUpdateAuthor: Joi.bool().default( + DEFAULT_OPTIONS.showLastUpdateAuthor, + ), + editUrl: Joi.alternatives().try(URISchema, Joi.function()), + editLocalizedFiles: Joi.boolean().default(DEFAULT_OPTIONS.editLocalizedFiles), }); export function validateOptions({ diff --git a/packages/docusaurus-plugin-content-pages/src/plugin-content-pages.d.ts b/packages/docusaurus-plugin-content-pages/src/plugin-content-pages.d.ts index f0a9230cdee0..1c7b03743786 100644 --- a/packages/docusaurus-plugin-content-pages/src/plugin-content-pages.d.ts +++ b/packages/docusaurus-plugin-content-pages/src/plugin-content-pages.d.ts @@ -8,6 +8,7 @@ declare module '@docusaurus/plugin-content-pages' { import type {MDXOptions} from '@docusaurus/mdx-loader'; import type {LoadContext, Plugin} from '@docusaurus/types'; + import type {FrontMatterLastUpdate, LastUpdateData} from '@docusaurus/utils'; export type Assets = { image?: string; @@ -20,6 +21,10 @@ declare module '@docusaurus/plugin-content-pages' { include: string[]; exclude: string[]; mdxPageComponent: string; + showLastUpdateTime: boolean; + showLastUpdateAuthor: boolean; + editUrl?: string | EditUrlFunction; + editLocalizedFiles?: boolean; }; export type Options = Partial; @@ -35,6 +40,7 @@ declare module '@docusaurus/plugin-content-pages' { readonly toc_max_heading_level?: number; readonly draft?: boolean; readonly unlisted?: boolean; + readonly last_update?: FrontMatterLastUpdate; }; export type JSXPageMetadata = { @@ -43,16 +49,31 @@ declare module '@docusaurus/plugin-content-pages' { source: string; }; - export type MDXPageMetadata = { + export type MDXPageMetadata = LastUpdateData & { type: 'mdx'; permalink: string; source: string; frontMatter: PageFrontMatter & {[key: string]: unknown}; + editUrl?: string; title?: string; description?: string; unlisted: boolean; }; + export type EditUrlFunction = (editUrlParams: { + /** + * The root content directory containing this post file, relative to the + * site path. Usually the same as `options.path` but can be localized + */ + pagesDirPath: string; + /** Path to this pages file, relative to `pagesDirPath`. */ + pagesPath: string; + /** @see {@link PagesPostMetadata.permalink} */ + permalink: string; + /** Locale name. */ + locale: string; + }) => string | undefined; + export type Metadata = JSXPageMetadata | MDXPageMetadata; export type LoadedContent = Metadata[]; diff --git a/packages/docusaurus-theme-classic/src/theme/MDXPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/MDXPage/index.tsx index c9222ad0b532..103dc3e69a1b 100644 --- a/packages/docusaurus-theme-classic/src/theme/MDXPage/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/MDXPage/index.tsx @@ -18,12 +18,21 @@ import TOC from '@theme/TOC'; import Unlisted from '@theme/Unlisted'; import type {Props} from '@theme/MDXPage'; +import EditMetaRow from '@theme/EditMetaRow'; import styles from './styles.module.css'; export default function MDXPage(props: Props): JSX.Element { const {content: MDXPageContent} = props; const { - metadata: {title, description, frontMatter, unlisted}, + metadata: { + title, + editUrl, + description, + frontMatter, + unlisted, + lastUpdatedBy, + lastUpdatedAt, + }, assets, } = MDXPageContent; const { @@ -33,6 +42,8 @@ export default function MDXPage(props: Props): JSX.Element { } = frontMatter; const image = assets.image ?? frontMatter.image; + const canDisplayEditMetaRow = !!(editUrl || lastUpdatedAt || lastUpdatedBy); + return ( + {canDisplayEditMetaRow && ( + + )} {!hideTableOfContents && MDXPageContent.toc.length > 0 && (
diff --git a/packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts b/packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts index 79cf8e2ae0cf..1cdcda3ce50a 100644 --- a/packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts +++ b/packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts @@ -76,4 +76,7 @@ export const ThemeClassNames = { blogFooterTagsRow: 'theme-blog-footer-tags-row', blogFooterEditMetaRow: 'theme-blog-footer-edit-meta-row', }, + pages: { + pageFooterEditMetaRow: 'theme-pages-footer-edit-meta-row', + }, } as const; diff --git a/project-words.txt b/project-words.txt index 4338cda1e9d0..a8d6f78c1382 100644 --- a/project-words.txt +++ b/project-words.txt @@ -224,6 +224,7 @@ opensearch opensearchdescription opensource optimizt +Orama orama Orta orta diff --git a/website/_dogfooding/dogfooding.config.ts b/website/_dogfooding/dogfooding.config.ts index 3e57c13c36ad..ebb6b22885c9 100644 --- a/website/_dogfooding/dogfooding.config.ts +++ b/website/_dogfooding/dogfooding.config.ts @@ -90,6 +90,10 @@ export const dogfoodingPluginInstances: PluginConfig[] = [ id: 'pages-tests', path: '_dogfooding/_pages tests', routeBasePath: '/tests/pages', + showLastUpdateTime: true, + showLastUpdateAuthor: true, + editUrl: ({pagesPath}) => + `https://github.com/facebook/docusaurus/edit/main/website/_dogfooding/_pages tests/${pagesPath}`, } satisfies PageOptions, ], diff --git a/website/docs/api/plugins/plugin-content-pages.mdx b/website/docs/api/plugins/plugin-content-pages.mdx index 8894e7861b4c..266c929d5a14 100644 --- a/website/docs/api/plugins/plugin-content-pages.mdx +++ b/website/docs/api/plugins/plugin-content-pages.mdx @@ -34,6 +34,8 @@ Accepted fields: | Name | Type | Default | Description | | --- | --- | --- | --- | | `path` | `string` | `'src/pages'` | Path to data on filesystem relative to site dir. Components in this directory will be automatically converted to pages. | +| `editUrl` | string \| [EditUrlFn](#EditUrlFn) | `undefined` | **Only for Markdown pages**. Base URL to edit your site. The final URL is computed by `editUrl + relativePostPath`. Using a function allows more nuanced control for each file. Omitting this variable entirely will disable edit links. | +| `editLocalizedFiles` | `boolean` | `false` | **Only for Markdown pages**. The edit URL will target the localized file, instead of the original unlocalized file. Ignored when `editUrl` is a function. | | `routeBasePath` | `string` | `'/'` | URL route for the pages section of your site. **DO NOT** include a trailing slash. | | `include` | `string[]` | `['**/*.{js,jsx,ts,tsx,md,mdx}']` | Matching files will be included and processed. | | `exclude` | `string[]` | _See example configuration_ | No route will be created for matching files. | @@ -42,11 +44,26 @@ Accepted fields: | `rehypePlugins` | `[]` | `any[]` | Rehype plugins passed to MDX. | | `beforeDefaultRemarkPlugins` | `any[]` | `[]` | Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins. | | `beforeDefaultRehypePlugins` | `any[]` | `[]` | Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins. | +| `showLastUpdateAuthor` | `boolean` | `false` | **Only for Markdown pages**. Whether to display the author who last updated the page. | +| `showLastUpdateTime` | `boolean` | `false` | **Only for Markdown pages**. Whether to display the last date the page post was updated. This requires access to git history during the build, so will not work correctly with shallow clones (a common default for CI systems). With GitHub `actions/checkout`, use`fetch-depth: 0`. | ```mdx-code-block ``` +### Types {#types} + +#### `EditUrlFn` {#EditUrlFn} + +```ts +type EditUrlFunction = (params: { + blogDirPath: string; + blogPath: string; + permalink: string; + locale: string; +}) => string | undefined; +``` + ### Example configuration {#ex-config} You can configure this plugin through preset options or plugin options. diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index 04dec0dacb5e..a5cdb17b4ae1 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -464,6 +464,14 @@ export default async function createConfigAsync() { } satisfies BlogOptions, pages: { remarkPlugins: [npm2yarn], + editUrl: ({locale, pagesPath}) => { + if (locale !== defaultLocale) { + return `https://crowdin.com/project/docusaurus-v2/${locale}`; + } + return `https://github.com/facebook/docusaurus/edit/main/website/src/pages/${pagesPath}`; + }, + showLastUpdateAuthor: true, + showLastUpdateTime: true, } satisfies PageOptions, theme: { customCss: [