alrayyes/wiki
1
0
Fork 0
mirror of https://github.com/alrayyes/wiki.git synced 2024-11-22 11:36:23 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

refactor: move emit from callback to helper file function (#704)

Browse source 
* Change emit from callback to helpers file function

* Update docs, remove commented code, improve type sig
This commit is contained in:
kabirgh 2024-01-18 18:56:14 +00:00 committed by GitHub
parent af811d824f
commit ce3dd0923b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
14 changed files with 69 additions and 58 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
docs/advanced/making plugins.md
View file

@ -216,22 +216,19 @@ export type QuartzEmitterPlugin<Options extends OptionType = undefined> = (
export type QuartzEmitterPluginInstance = { export type QuartzEmitterPluginInstance = {
name: string name: string
emit( emit(ctx: BuildCtx, content: ProcessedContent[], resources: StaticResources): Promise<FilePath[]>
ctx: BuildCtx,
content: ProcessedContent[],
resources: StaticResources,
emitCallback: EmitCallback,
): Promise<FilePath[]>
getQuartzComponents(ctx: BuildCtx): QuartzComponent[] getQuartzComponents(ctx: BuildCtx): QuartzComponent[]
} }
``` ```
An emitter plugin must define a `name` field an `emit` function and a `getQuartzComponents` function. `emit` is responsible for looking at all the parsed and filtered content and then appropriately creating files and returning a list of paths to files the plugin created. An emitter plugin must define a `name` field, an `emit` function, and a `getQuartzComponents` function. `emit` is responsible for looking at all the parsed and filtered content and then appropriately creating files and returning a list of paths to files the plugin created.
Creating new files can be done via regular Node [fs module](https://nodejs.org/api/fs.html) (i.e. `fs.cp` or `fs.writeFile`) or via the `emitCallback` if you are creating files that contain text. The `emitCallback` function is the 4th argument of the emit function. Its interface looks something like this: Creating new files can be done via regular Node [fs module](https://nodejs.org/api/fs.html) (i.e. `fs.cp` or `fs.writeFile`) or via the `write` function in `quartz/plugins/emitters/helpers.ts` if you are creating files that contain text. `write` has the following signature:
```ts ```ts
export type EmitCallback = (data: { export type WriteOptions = (data: {
// the build context
ctx: BuildCtx
// the name of the file to emit (not including the file extension) // the name of the file to emit (not including the file extension)
slug: ServerSlug slug: ServerSlug
// the file extension // the file extension

6
quartz/plugins/emitters/404.tsx
View file

@ -7,6 +7,7 @@ import { FilePath, FullSlug } from "../../util/path"
import { sharedPageComponents } from "../../../quartz.layout" import { sharedPageComponents } from "../../../quartz.layout"
import { NotFound } from "../../components" import { NotFound } from "../../components"
import { defaultProcessedContent } from "../vfile" import { defaultProcessedContent } from "../vfile"
import { write } from "./helpers"
export const NotFoundPage: QuartzEmitterPlugin = () => { export const NotFoundPage: QuartzEmitterPlugin = () => {
const opts: FullPageLayout = { const opts: FullPageLayout = {
@ -25,7 +26,7 @@ export const NotFoundPage: QuartzEmitterPlugin = () => {
getQuartzComponents() { getQuartzComponents() {
return [Head, Body, pageBody, Footer] return [Head, Body, pageBody, Footer]
}, },
async emit(ctx, _content, resources, emit): Promise<FilePath[]> { async emit(ctx, _content, resources): Promise<FilePath[]> {
const cfg = ctx.cfg.configuration const cfg = ctx.cfg.configuration
const slug = "404" as FullSlug const slug = "404" as FullSlug
@ -48,7 +49,8 @@ export const NotFoundPage: QuartzEmitterPlugin = () => {
} }
return [ return [
await emit({ await write({
ctx,
content: renderPage(slug, componentData, opts, externalResources), content: renderPage(slug, componentData, opts, externalResources),
slug, slug,
ext: ".html", ext: ".html",

7
quartz/plugins/emitters/aliases.ts
View file

@ -1,13 +1,15 @@
import { FilePath, FullSlug, joinSegments, resolveRelative, simplifySlug } from "../../util/path" import { FilePath, FullSlug, joinSegments, resolveRelative, simplifySlug } from "../../util/path"
import { QuartzEmitterPlugin } from "../types" import { QuartzEmitterPlugin } from "../types"
import path from "path" import path from "path"
import { write } from "./helpers"
export const AliasRedirects: QuartzEmitterPlugin = () => ({ export const AliasRedirects: QuartzEmitterPlugin = () => ({
name: "AliasRedirects", name: "AliasRedirects",
getQuartzComponents() { getQuartzComponents() {
return [] return []
}, },
async emit({ argv }, content, _resources, emit): Promise<FilePath[]> { async emit(ctx, content, _resources): Promise<FilePath[]> {
const { argv } = ctx
const fps: FilePath[] = [] const fps: FilePath[] = []
for (const [_tree, file] of content) { for (const [_tree, file] of content) {
@ -32,7 +34,8 @@ export const AliasRedirects: QuartzEmitterPlugin = () => ({
} }
const redirUrl = resolveRelative(slug, file.data.slug!) const redirUrl = resolveRelative(slug, file.data.slug!)
const fp = await emit({ const fp = await write({
ctx,
content: ` content: `
<!DOCTYPE html> <!DOCTYPE html>
<html lang="en-us"> <html lang="en-us">

2
quartz/plugins/emitters/assets.ts
View file

@ -10,7 +10,7 @@ export const Assets: QuartzEmitterPlugin = () => {
getQuartzComponents() { getQuartzComponents() {
return [] return []
}, },
async emit({ argv, cfg }, _content, _resources, _emit): Promise<FilePath[]> { async emit({ argv, cfg }, _content, _resources): Promise<FilePath[]> {
// glob all non MD/MDX/HTML files in content folder and copy it over // glob all non MD/MDX/HTML files in content folder and copy it over
const assetsPath = argv.output const assetsPath = argv.output
const fps = await glob("**", argv.directory, ["**/*.md", ...cfg.configuration.ignorePatterns]) const fps = await glob("**", argv.directory, ["**/*.md", ...cfg.configuration.ignorePatterns])

2
quartz/plugins/emitters/cname.ts
View file

@ -13,7 +13,7 @@ export const CNAME: QuartzEmitterPlugin = () => ({
getQuartzComponents() { getQuartzComponents() {
return [] return []
}, },
async emit({ argv, cfg }, _content, _resources, _emit): Promise<FilePath[]> { async emit({ argv, cfg }, _content, _resources): Promise<FilePath[]> {
if (!cfg.configuration.baseUrl) { if (!cfg.configuration.baseUrl) {
console.warn(chalk.yellow("CNAME emitter requires `baseUrl` to be set in your configuration")) console.warn(chalk.yellow("CNAME emitter requires `baseUrl` to be set in your configuration"))
return [] return []

16
quartz/plugins/emitters/componentResources.ts
View file

@ -13,6 +13,7 @@ import { QuartzComponent } from "../../components/types"
import { googleFontHref, joinStyles } from "../../util/theme" import { googleFontHref, joinStyles } from "../../util/theme"
import { Features, transform } from "lightningcss" import { Features, transform } from "lightningcss"
import { transform as transpile } from "esbuild" import { transform as transpile } from "esbuild"
import { write } from "./helpers"
type ComponentResources = { type ComponentResources = {
css: string[] css: string[]
@ -93,7 +94,7 @@ function addGlobalPageResources(
function gtag() { dataLayer.push(arguments); } function gtag() { dataLayer.push(arguments); }
gtag("js", new Date()); gtag("js", new Date());
gtag("config", "${tagId}", { send_page_view: false }); gtag("config", "${tagId}", { send_page_view: false });
document.addEventListener("nav", () => { document.addEventListener("nav", () => {
gtag("event", "page_view", { gtag("event", "page_view", {
page_title: document.title, page_title: document.title,
@ -121,7 +122,7 @@ function addGlobalPageResources(
umamiScript.src = "https://analytics.umami.is/script.js" umamiScript.src = "https://analytics.umami.is/script.js"
umamiScript.setAttribute("data-website-id", "${cfg.analytics.websiteId}") umamiScript.setAttribute("data-website-id", "${cfg.analytics.websiteId}")
umamiScript.async = true umamiScript.async = true
document.head.appendChild(umamiScript) document.head.appendChild(umamiScript)
`) `)
} }
@ -168,7 +169,7 @@ export const ComponentResources: QuartzEmitterPlugin<Options> = (opts?: Partial<
getQuartzComponents() { getQuartzComponents() {
return [] return []
}, },
async emit(ctx, _content, resources, emit): Promise<FilePath[]> { async emit(ctx, _content, resources): Promise<FilePath[]> {
// component specific scripts and styles // component specific scripts and styles
const componentResources = getComponentResources(ctx) const componentResources = getComponentResources(ctx)
// important that this goes *after* component scripts // important that this goes *after* component scripts
@ -190,7 +191,8 @@ export const ComponentResources: QuartzEmitterPlugin<Options> = (opts?: Partial<
]) ])
const fps = await Promise.all([ const fps = await Promise.all([
emit({ write({
ctx,
slug: "index" as FullSlug, slug: "index" as FullSlug,
ext: ".css", ext: ".css",
content: transform({ content: transform({
@ -207,12 +209,14 @@ export const ComponentResources: QuartzEmitterPlugin<Options> = (opts?: Partial<
include: Features.MediaQueries, include: Features.MediaQueries,
}).code.toString(), }).code.toString(),
}), }),
emit({ write({
ctx,
slug: "prescript" as FullSlug, slug: "prescript" as FullSlug,
ext: ".js", ext: ".js",
content: prescript, content: prescript,
}), }),
emit({ write({
ctx,
slug: "postscript" as FullSlug, slug: "postscript" as FullSlug,
ext: ".js", ext: ".js",
content: postscript, content: postscript,

12
quartz/plugins/emitters/contentIndex.ts
View file

@ -6,6 +6,7 @@ import { FilePath, FullSlug, SimpleSlug, joinSegments, simplifySlug } from "../.
import { QuartzEmitterPlugin } from "../types" import { QuartzEmitterPlugin } from "../types"
import { toHtml } from "hast-util-to-html" import { toHtml } from "hast-util-to-html"
import path from "path" import path from "path"
import { write } from "./helpers"
export type ContentIndex = Map<FullSlug, ContentDetails> export type ContentIndex = Map<FullSlug, ContentDetails>
export type ContentDetails = { export type ContentDetails = {
@ -91,7 +92,7 @@ export const ContentIndex: QuartzEmitterPlugin<Partial<Options>> = (opts) => {
opts = { ...defaultOptions, ...opts } opts = { ...defaultOptions, ...opts }
return { return {
name: "ContentIndex", name: "ContentIndex",
async emit(ctx, content, _resources, emit) { async emit(ctx, content, _resources) {
const cfg = ctx.cfg.configuration const cfg = ctx.cfg.configuration
const emitted: FilePath[] = [] const emitted: FilePath[] = []
const linkIndex: ContentIndex = new Map() const linkIndex: ContentIndex = new Map()
@ -115,7 +116,8 @@ export const ContentIndex: QuartzEmitterPlugin<Partial<Options>> = (opts) => {
if (opts?.enableSiteMap) { if (opts?.enableSiteMap) {
emitted.push( emitted.push(
await emit({ await write({
ctx,
content: generateSiteMap(cfg, linkIndex), content: generateSiteMap(cfg, linkIndex),
slug: "sitemap" as FullSlug, slug: "sitemap" as FullSlug,
ext: ".xml", ext: ".xml",
@ -125,7 +127,8 @@ export const ContentIndex: QuartzEmitterPlugin<Partial<Options>> = (opts) => {
if (opts?.enableRSS) { if (opts?.enableRSS) {
emitted.push( emitted.push(
await emit({ await write({
ctx,
content: generateRSSFeed(cfg, linkIndex, opts.rssLimit), content: generateRSSFeed(cfg, linkIndex, opts.rssLimit),
slug: "index" as FullSlug, slug: "index" as FullSlug,
ext: ".xml", ext: ".xml",
@ -146,7 +149,8 @@ export const ContentIndex: QuartzEmitterPlugin<Partial<Options>> = (opts) => {
) )
emitted.push( emitted.push(
await emit({ await write({
ctx,
content: JSON.stringify(simplifiedIndex), content: JSON.stringify(simplifiedIndex),
slug: fp, slug: fp,
ext: ".json", ext: ".json",

6
quartz/plugins/emitters/contentPage.tsx
View file

@ -8,6 +8,7 @@ import { FilePath, pathToRoot } from "../../util/path"
import { defaultContentPageLayout, sharedPageComponents } from "../../../quartz.layout" import { defaultContentPageLayout, sharedPageComponents } from "../../../quartz.layout"
import { Content } from "../../components" import { Content } from "../../components"
import chalk from "chalk" import chalk from "chalk"
import { write } from "./helpers"
export const ContentPage: QuartzEmitterPlugin<Partial<FullPageLayout>> = (userOpts) => { export const ContentPage: QuartzEmitterPlugin<Partial<FullPageLayout>> = (userOpts) => {
const opts: FullPageLayout = { const opts: FullPageLayout = {
@ -26,7 +27,7 @@ export const ContentPage: QuartzEmitterPlugin<Partial<FullPageLayout>> = (userOp
getQuartzComponents() { getQuartzComponents() {
return [Head, Header, Body, ...header, ...beforeBody, pageBody, ...left, ...right, Footer] return [Head, Header, Body, ...header, ...beforeBody, pageBody, ...left, ...right, Footer]
}, },
async emit(ctx, content, resources, emit): Promise<FilePath[]> { async emit(ctx, content, resources): Promise<FilePath[]> {
const cfg = ctx.cfg.configuration const cfg = ctx.cfg.configuration
const fps: FilePath[] = [] const fps: FilePath[] = []
const allFiles = content.map((c) => c[1].data) const allFiles = content.map((c) => c[1].data)
@ -49,7 +50,8 @@ export const ContentPage: QuartzEmitterPlugin<Partial<FullPageLayout>> = (userOp
} }
const content = renderPage(slug, componentData, opts, externalResources) const content = renderPage(slug, componentData, opts, externalResources)
const fp = await emit({ const fp = await write({
ctx,
content, content,
slug, slug,
ext: ".html", ext: ".html",

6
quartz/plugins/emitters/folderPage.tsx
View file

@ -17,6 +17,7 @@ import {
} from "../../util/path" } from "../../util/path"
import { defaultListPageLayout, sharedPageComponents } from "../../../quartz.layout" import { defaultListPageLayout, sharedPageComponents } from "../../../quartz.layout"
import { FolderContent } from "../../components" import { FolderContent } from "../../components"
import { write } from "./helpers"
export const FolderPage: QuartzEmitterPlugin<FullPageLayout> = (userOpts) => { export const FolderPage: QuartzEmitterPlugin<FullPageLayout> = (userOpts) => {
const opts: FullPageLayout = { const opts: FullPageLayout = {
@ -35,7 +36,7 @@ export const FolderPage: QuartzEmitterPlugin<FullPageLayout> = (userOpts) => {
getQuartzComponents() { getQuartzComponents() {
return [Head, Header, Body, ...header, ...beforeBody, pageBody, ...left, ...right, Footer] return [Head, Header, Body, ...header, ...beforeBody, pageBody, ...left, ...right, Footer]
}, },
async emit(ctx, content, resources, emit): Promise<FilePath[]> { async emit(ctx, content, resources): Promise<FilePath[]> {
const fps: FilePath[] = [] const fps: FilePath[] = []
const allFiles = content.map((c) => c[1].data) const allFiles = content.map((c) => c[1].data)
const cfg = ctx.cfg.configuration const cfg = ctx.cfg.configuration
@ -82,7 +83,8 @@ export const FolderPage: QuartzEmitterPlugin<FullPageLayout> = (userOpts) => {
} }
const content = renderPage(slug, componentData, opts, externalResources) const content = renderPage(slug, componentData, opts, externalResources)
const fp = await emit({ const fp = await write({
ctx,
content, content,
slug, slug,
ext: ".html", ext: ".html",

19
quartz/plugins/emitters/helpers.ts Normal file
View file

@ -0,0 +1,19 @@
import path from "path"
import fs from "fs"
import { BuildCtx } from "../../util/ctx"
import { FilePath, FullSlug, joinSegments } from "../../util/path"
type WriteOptions = {
ctx: BuildCtx
slug: FullSlug
ext: `.${string}` | ""
content: string
}
export const write = async ({ ctx, slug, ext, content }: WriteOptions): Promise<FilePath> => {
const pathToPage = joinSegments(ctx.argv.output, slug + ext) as FilePath
const dir = path.dirname(pathToPage)
await fs.promises.mkdir(dir, { recursive: true })
await fs.promises.writeFile(pathToPage, content)
return pathToPage
}

2
quartz/plugins/emitters/static.ts
View file

@ -8,7 +8,7 @@ export const Static: QuartzEmitterPlugin = () => ({
getQuartzComponents() { getQuartzComponents() {
return [] return []
}, },
async emit({ argv, cfg }, _content, _resources, _emit): Promise<FilePath[]> { async emit({ argv, cfg }, _content, _resources): Promise<FilePath[]> {
const staticPath = joinSegments(QUARTZ, "static") const staticPath = joinSegments(QUARTZ, "static")
const fps = await glob("**", staticPath, cfg.configuration.ignorePatterns) const fps = await glob("**", staticPath, cfg.configuration.ignorePatterns)
await fs.promises.cp(staticPath, joinSegments(argv.output, "static"), { await fs.promises.cp(staticPath, joinSegments(argv.output, "static"), {

6
quartz/plugins/emitters/tagPage.tsx
View file

@ -14,6 +14,7 @@ import {
} from "../../util/path" } from "../../util/path"
import { defaultListPageLayout, sharedPageComponents } from "../../../quartz.layout" import { defaultListPageLayout, sharedPageComponents } from "../../../quartz.layout"
import { TagContent } from "../../components" import { TagContent } from "../../components"
import { write } from "./helpers"
export const TagPage: QuartzEmitterPlugin<FullPageLayout> = (userOpts) => { export const TagPage: QuartzEmitterPlugin<FullPageLayout> = (userOpts) => {
const opts: FullPageLayout = { const opts: FullPageLayout = {
@ -32,7 +33,7 @@ export const TagPage: QuartzEmitterPlugin<FullPageLayout> = (userOpts) => {
getQuartzComponents() { getQuartzComponents() {
return [Head, Header, Body, ...header, ...beforeBody, pageBody, ...left, ...right, Footer] return [Head, Header, Body, ...header, ...beforeBody, pageBody, ...left, ...right, Footer]
}, },
async emit(ctx, content, resources, emit): Promise<FilePath[]> { async emit(ctx, content, resources): Promise<FilePath[]> {
const fps: FilePath[] = [] const fps: FilePath[] = []
const allFiles = content.map((c) => c[1].data) const allFiles = content.map((c) => c[1].data)
const cfg = ctx.cfg.configuration const cfg = ctx.cfg.configuration
@ -81,7 +82,8 @@ export const TagPage: QuartzEmitterPlugin<FullPageLayout> = (userOpts) => {
} }
const content = renderPage(slug, componentData, opts, externalResources) const content = renderPage(slug, componentData, opts, externalResources)
const fp = await emit({ const fp = await write({
ctx,
content, content,
slug: file.data.slug!, slug: file.data.slug!,
ext: ".html", ext: ".html",

15
quartz/plugins/types.ts
View file

@ -36,19 +36,6 @@ export type QuartzEmitterPlugin<Options extends OptionType = undefined> = (
) => QuartzEmitterPluginInstance ) => QuartzEmitterPluginInstance
export type QuartzEmitterPluginInstance = { export type QuartzEmitterPluginInstance = {
name: string name: string
emit( emit(ctx: BuildCtx, content: ProcessedContent[], resources: StaticResources): Promise<FilePath[]>
ctx: BuildCtx,
content: ProcessedContent[],
resources: StaticResources,
emitCallback: EmitCallback,
): Promise<FilePath[]>
getQuartzComponents(ctx: BuildCtx): QuartzComponent[] getQuartzComponents(ctx: BuildCtx): QuartzComponent[]
} }
export interface EmitOptions {
slug: FullSlug
ext: `.${string}` | ""
content: string
}
export type EmitCallback = (data: EmitOptions) => Promise<FilePath>

13
quartz/processors/emit.ts
View file

@ -1,10 +1,6 @@
import path from "path"
import fs from "fs"
import { PerfTimer } from "../util/perf" import { PerfTimer } from "../util/perf"
import { getStaticResourcesFromPlugins } from "../plugins" import { getStaticResourcesFromPlugins } from "../plugins"
import { EmitCallback } from "../plugins/types"
import { ProcessedContent } from "../plugins/vfile" import { ProcessedContent } from "../plugins/vfile"
import { FilePath, joinSegments } from "../util/path"
import { QuartzLogger } from "../util/log" import { QuartzLogger } from "../util/log"
import { trace } from "../util/trace" import { trace } from "../util/trace"
import { BuildCtx } from "../util/ctx" import { BuildCtx } from "../util/ctx"
@ -15,19 +11,12 @@ export async function emitContent(ctx: BuildCtx, content: ProcessedContent[]) {
const log = new QuartzLogger(ctx.argv.verbose) const log = new QuartzLogger(ctx.argv.verbose)
log.start(`Emitting output files`) log.start(`Emitting output files`)
const emit: EmitCallback = async ({ slug, ext, content }) => {
const pathToPage = joinSegments(argv.output, slug + ext) as FilePath
const dir = path.dirname(pathToPage)
await fs.promises.mkdir(dir, { recursive: true })
await fs.promises.writeFile(pathToPage, content)
return pathToPage
}
let emittedFiles = 0 let emittedFiles = 0
const staticResources = getStaticResourcesFromPlugins(ctx) const staticResources = getStaticResourcesFromPlugins(ctx)
for (const emitter of cfg.plugins.emitters) { for (const emitter of cfg.plugins.emitters) {
try { try {
const emitted = await emitter.emit(ctx, content, staticResources, emit) const emitted = await emitter.emit(ctx, content, staticResources)
emittedFiles += emitted.length emittedFiles += emitted.length
if (ctx.argv.verbose) { if (ctx.argv.verbose) {