plugin integration round 2

This commit is contained in:
Jacky Zhao 2023-05-30 08:02:20 -07:00
parent 70a05fccd5
commit 62d0c4bd1a
29 changed files with 3863 additions and 100 deletions

3180
package-lock.json generated

File diff suppressed because it is too large Load Diff

View File

@ -1,7 +1,7 @@
{
"name": "@jackyzha0/quartz",
"description": "🌱 publish your digital garden and notes as a website",
"version": "4.1.0",
"version": "4.0.3",
"author": "jackyzha0 <j.zhao2k19@gmail.com>",
"license": "MIT",
"homepage": "https://quartz.jzhao.xyz",
@ -9,6 +9,10 @@
"type": "git",
"url": "https://github.com/jackyzha0/quartz.git"
},
"scripts": {
"typecheck": "tsc --noEmit",
"cycle-detect": "madge --circular --extensions ts quartz/index.ts"
},
"keywords": [
"site generator",
"ssg",
@ -22,19 +26,25 @@
},
"dependencies": {
"@inquirer/prompts": "^1.0.3",
"@napi-rs/simple-git": "^0.1.8",
"chalk": "^4.1.2",
"cli-spinner": "^0.2.10",
"esbuild": "0.17.18",
"globby": "^13.1.4",
"gray-matter": "^4.0.3",
"hast-util-to-string": "^2.0.0",
"preact": "^10.14.1",
"preact-render-to-string": "^6.0.3",
"pretty-time": "^1.1.0",
"rehype-react": "^7.2.0",
"rehype-katex": "^6.0.3",
"remark": "^14.0.2",
"remark-frontmatter": "^4.0.1",
"remark-gfm": "^3.0.1",
"remark-math": "^5.1.1",
"remark-parse": "^10.0.1",
"remark-rehype": "^10.1.0",
"remark-smartypants": "^2.0.0",
"require-from-string": "^2.0.2",
"rimraf": "^5.0.0",
"rimraf": "^5.0.1",
"serve-handler": "^6.1.5",
"to-vfile": "^7.2.4",
"unified": "^10.1.2",
@ -44,12 +54,13 @@
"devDependencies": {
"@types/cli-spinner": "^0.2.1",
"@types/hast": "^2.3.4",
"@types/node": "^20.1.2",
"@types/pretty-time": "^1.1.2",
"@types/require-from-string": "^1.2.1",
"@types/serve-handler": "^6.1.1",
"@types/yargs": "^17.0.24",
"@types/node": "^20.1.2",
"esbuild": "0.17.18",
"esbuild": "^0.17.18",
"madge": "^6.0.0",
"typescript": "^5.0.4"
}
}

57
quartz.config.ts Normal file
View File

@ -0,0 +1,57 @@
import { buildQuartz } from "./quartz"
import { ContentPage, CreatedModifiedDate, Description, FrontMatter, GitHubFlavoredMarkdown, Katex, RemoveDrafts } from "./quartz/plugins"
export default buildQuartz({
configuration: {
siteTitle: "🪴 Quartz 4.0",
prettyLinks: true,
markdownLinkResolution: 'absolute',
enableLatex: true,
enableSPA: true,
ignorePatterns: [],
},
plugins: {
transformers: [
new FrontMatter(),
new GitHubFlavoredMarkdown(),
new Katex(),
new Description(),
new CreatedModifiedDate()
],
filters: [
new RemoveDrafts()
],
emitters: [
new ContentPage()
]
},
theme: {
typography: { // loaded from Google Fonts
header: "Schibsted Grotesk",
body: "Source Sans Pro",
code: "IBM Plex Mono",
},
colors: {
lightMode: {
light: '#faf8f8',
lightgray: '#e8e8e8',
gray: '#dadada',
darkgray: '#4e4e4e',
dark: '#141021',
secondary: '#284b63',
tertiary: '#84a59d',
highlight: 'rgba(143, 159, 169, 0.15)',
},
darkMode: {
light: '#1e1e21',
lightgray: '#292629',
gray: '#343434',
darkgray: '#d4d4d4',
dark: '#fbfffe',
secondary: '#7b97aa',
tertiary: '#84a59d',
highlight: 'rgba(143, 159, 169, 0.15)',
},
}
}
})

View File

@ -1,2 +1,80 @@
#!/usr/bin/env node
console.log('hello world')
import { readFileSync } from 'fs'
import yargs from 'yargs'
import { hideBin } from 'yargs/helpers'
import esbuild from 'esbuild'
import chalk from 'chalk'
import requireFromString from 'require-from-string'
const fp = "./quartz.config.ts"
const { version } = JSON.parse(readFileSync("./package.json").toString())
export const BuildArgv = {
output: {
string: true,
alias: ['o'],
default: 'public',
describe: 'output folder for files'
},
clean: {
boolean: true,
default: false,
describe: 'clean the output folder before building'
},
serve: {
boolean: true,
default: false,
describe: 'run a local server to preview your Quartz'
},
port: {
number: true,
default: 8080,
describe: 'port to serve Quartz on'
},
directory: {
string: true,
alias: ['d'],
default: 'content',
describe: 'directory to look for content files'
},
verbose: {
boolean: true,
alias: ['v'],
default: false,
describe: 'print out extra logging information'
}
}
yargs(hideBin(process.argv))
.scriptName("quartz")
.version(version)
.usage('$0 <cmd> [args]')
.command('build', 'Build Quartz into a bundle of static HTML files', BuildArgv, async (argv) => {
const out = await esbuild.build({
entryPoints: [fp],
write: false,
minifySyntax: true,
minifyWhitespace: true,
bundle: true,
keepNames: true,
platform: "node",
format: "cjs",
jsx: "automatic",
jsxImportSource: "preact",
external: ["@napi-rs/simple-git"]
}).catch(err => {
console.error(`${chalk.red("Couldn't parse Quartz configuration:")} ${fp}`)
console.log(`Reason: ${chalk.grey(err)}`)
console.log("hint: make sure all the required dependencies are installed (run `npm install`)")
process.exit(1)
})
const mod = out.outputFiles[0].text
const init = requireFromString(mod, fp).default
init(argv, version)
})
.showHelpOnFail(false)
.help()
.strict()
.demandCommand()
.argv

40
quartz/cfg.ts Normal file
View File

@ -0,0 +1,40 @@
import { PluginTypes } from "./plugins"
export interface ColorScheme {
light: string,
lightgray: string,
gray: string,
darkgray: string,
dark: string,
secondary: string,
tertiary: string,
highlight: string
}
export interface QuartzConfig {
configuration: {
siteTitle: string,
/** How to resolve Markdown paths */
markdownLinkResolution: 'absolute' | 'relative'
/** Strips folders from a link so that it looks nice */
prettyLinks: boolean
/** Whether to process and render latex (increases bundle size) */
enableLatex: boolean,
/** Whether to enable single-page-app style rendering. this prevents flashes of unstyled content and improves smoothness of Quartz */
enableSPA: boolean,
/** Glob patterns to not search */
ignorePatterns: string[],
},
plugins: PluginTypes,
theme: {
typography: {
header: string,
body: string,
code: string
},
colors: {
lightMode: ColorScheme,
darkMode: ColorScheme
}
}
}

View File

@ -0,0 +1,28 @@
import { StaticResources } from "../resources"
interface Props {
title: string,
description: string,
externalResources: StaticResources,
baseDir: string
}
export default function({ title, description, externalResources, baseDir }: Props) {
const { css, js } = externalResources
const iconPath = baseDir + "/static/icon.png"
const ogImagePath = baseDir + "/static/og-image.png"
return <head>
<title>{title}</title>
<meta property="og:title" content={title} />
<meta property="og:description" content={title} />
<meta property="og:image" content={ogImagePath} />
<meta property="og:width" content="1200" />
<meta property="og:height" content="675" />
<link rel="icon" href={iconPath} />
<meta name="description" content={description} />
<meta name="generator" content="Quartz" />
<meta charSet="UTF-8" />
{css.map(href => <link key={href} href={href} rel="stylesheet" type="text/css" />)}
{js.filter(resource => resource.loadTime === "beforeDOMReady").map(resource => <script key={resource.src} src={resource.src} />)}
</head>
}

66
quartz/index.ts Normal file
View File

@ -0,0 +1,66 @@
import path from "path"
import { QuartzConfig } from "./cfg"
import { PerfTimer } from "./perf"
import { rimraf } from "rimraf"
import { globby } from "globby"
import chalk from "chalk"
import http from "http"
import serveHandler from "serve-handler"
import { createProcessor, parseMarkdown } from "./processors/parse"
interface Argv {
directory: string
verbose: boolean
output: string
clean: boolean
serve: boolean
port: number
}
export function buildQuartz(cfg: QuartzConfig) {
return async (argv: Argv, version: string) => {
console.log(chalk.bgGreen.black(`\n Quartz v${version} \n`))
const perf = new PerfTimer()
const output = path.join(argv.directory, argv.output)
// clean
if (argv.clean) {
perf.addEvent('clean')
await rimraf(output)
if (argv.verbose) {
console.log(`Cleaned output directory \`${output}\` in ${perf.timeSince('clean')}`)
}
}
// glob
perf.addEvent('glob')
const fps = await globby('**/*.md', {
cwd: argv.directory,
ignore: [...cfg.configuration.ignorePatterns, 'quartz/**'],
gitignore: true,
})
if (argv.verbose) {
console.log(`Found ${fps.length} input files in ${perf.timeSince('glob')}`)
}
const processor = createProcessor(cfg.plugins.transformers)
const filePaths = fps.map(fp => `${argv.directory}${path.sep}${fp}`)
const parsedFiles = await parseMarkdown(processor, argv.directory, filePaths, argv.verbose)
// const filteredContent = filterContent(cfg.plugins.filters, processedContent, argv.verbose)
// await emitContent(argv.directory, output, cfg, filteredContent, argv.verbose)
console.log(chalk.green(`Done in ${perf.timeSince()}`))
if (argv.serve) {
const server = http.createServer(async (req, res) => {
return serveHandler(req, res, {
public: output,
directoryListing: false
})
})
server.listen(argv.port)
console.log(`Started a Quartz server listening at http://localhost:${argv.port}`)
console.log('hint: exit with ctrl+c')
}
}
}

19
quartz/path.ts Normal file
View File

@ -0,0 +1,19 @@
import path from 'path'
// Replaces all whitespace with dashes and URI encodes the rest
export function pathToSlug(fp: string): string {
const { dir, name } = path.parse(fp)
let slug = path.join('/', dir, name)
slug = slug.replace(/\s/g, '-')
return slug
}
// resolve /a/b/c to ../../
export function resolveToRoot(slug: string): string {
let fp = slug
if (fp.endsWith("/index")) {
fp = fp.slice(0, -"/index".length)
}
return "./" + path.relative(fp, path.posix.sep)
}

19
quartz/perf.ts Normal file
View File

@ -0,0 +1,19 @@
import chalk from 'chalk'
import pretty from 'pretty-time'
export class PerfTimer {
evts: { [key: string]: [number, number] }
constructor() {
this.evts = {}
this.addEvent('start')
}
addEvent(evtName: string) {
this.evts[evtName] = process.hrtime()
}
timeSince(evtName?: string): string {
return chalk.yellow(pretty(process.hrtime(this.evts[evtName ?? 'start'])))
}
}

View File

@ -0,0 +1,26 @@
import { resolveToRoot } from "../../path"
import { EmitCallback, QuartzEmitterPlugin } from "../types"
import { ProcessedContent } from "../vfile"
export class ContentPage extends QuartzEmitterPlugin {
name = "ContentPage"
async emit(content: ProcessedContent[], emit: EmitCallback): Promise<string[]> {
const fps: string[] = []
for (const [tree, file] of content) {
const pathToRoot = resolveToRoot(file.data.slug!)
const fp = file.data.slug + ".html"
await emit({
title: file.data.frontmatter?.title ?? "Untitled",
description: file.data.description ?? "",
slug: file.data.slug!,
ext: ".html",
})
// TODO: process aliases
fps.push(fp)
}
return fps
}
}

View File

@ -0,0 +1 @@
export { ContentPage } from './contentPage'

View File

@ -0,0 +1,10 @@
import { QuartzFilterPlugin } from "../types"
import { ProcessedContent } from "../vfile"
export class RemoveDrafts extends QuartzFilterPlugin {
name = "RemoveDrafts"
shouldPublish([_tree, vfile]: ProcessedContent): boolean {
const draftFlag: boolean = vfile.data?.frontmatter?.draft ?? false
return !draftFlag
}
}

View File

@ -0,0 +1,10 @@
import { QuartzFilterPlugin } from "../types"
import { ProcessedContent } from "../vfile"
export class ExplicitPublish extends QuartzFilterPlugin {
name = "ExplicitPublish"
shouldPublish([_tree, vfile]: ProcessedContent): boolean {
const publishFlag: boolean = vfile.data?.frontmatter?.publish ?? false
return publishFlag
}
}

View File

@ -0,0 +1,2 @@
export { RemoveDrafts } from './draft'
export { ExplicitPublish } from './explicit'

33
quartz/plugins/index.ts Normal file
View File

@ -0,0 +1,33 @@
import { StaticResources } from '../resources'
import { PluginTypes } from './types'
export function getStaticResourcesFromPlugins(plugins: PluginTypes) {
const staticResources: StaticResources = {
css: [],
js: [],
}
for (const plugin of plugins.transformers) {
const res = plugin.externalResources
if (res?.js) {
staticResources.js = staticResources.js.concat(res.js)
}
if (res?.css) {
staticResources.css = staticResources.css.concat(res.css)
}
}
return staticResources
}
export * from './transformers'
export * from './filters'
export * from './emitters'
declare module 'vfile' {
// inserted in processors.ts
interface DataMap {
slug: string
filePath: string
}
}

View File

@ -0,0 +1,54 @@
import { PluggableList } from "unified"
import { Root as HTMLRoot } from 'hast'
import { toString } from "hast-util-to-string"
import { QuartzTransformerPlugin } from "../types"
export interface Options {
descriptionLength: number
}
const defaultOptions: Options = {
descriptionLength: 150
}
export class Description extends QuartzTransformerPlugin {
name = "Description"
opts: Options
constructor(opts?: Options) {
super()
this.opts = { ...defaultOptions, ...opts }
}
markdownPlugins(): PluggableList {
return []
}
htmlPlugins(): PluggableList {
return [
() => {
return async (tree: HTMLRoot, file) => {
const frontMatterDescription = file.data.frontmatter?.description
const desc = frontMatterDescription ?? toString(tree)
const sentences = desc.replace(/\s+/g, ' ').split('.')
let finalDesc = ""
let sentenceIdx = 0
const len = this.opts.descriptionLength
while (finalDesc.length < len) {
finalDesc += sentences[sentenceIdx] + '.'
sentenceIdx++
}
file.data.description = finalDesc
}
}
]
}
}
declare module 'vfile' {
interface DataMap {
description: string
}
}

View File

@ -0,0 +1,55 @@
import { PluggableList } from "unified"
import matter from "gray-matter"
import remarkFrontmatter from 'remark-frontmatter'
import { QuartzTransformerPlugin } from "../types"
export interface Options {
language: 'yaml' | 'toml',
delims: string | string[]
}
const defaultOptions: Options = {
language: 'yaml',
delims: '---'
}
export class FrontMatter extends QuartzTransformerPlugin {
name = "FrontMatter"
opts: Options
constructor(opts?: Options) {
super()
this.opts = { ...defaultOptions, ...opts }
}
markdownPlugins(): PluggableList {
return [
remarkFrontmatter,
() => {
return (_, file) => {
const { data } = matter(file.value, this.opts)
// fill in frontmatter
file.data.frontmatter = {
title: file.stem ?? "Untitled",
tags: [],
...data
}
}
}
]
}
htmlPlugins(): PluggableList {
return []
}
}
declare module 'vfile' {
interface DataMap {
frontmatter: { [key: string]: any } & {
title: string
tags: string[]
}
}
}

View File

@ -0,0 +1,30 @@
import { PluggableList } from "unified"
import remarkGfm from "remark-gfm"
import smartypants from 'remark-smartypants'
import { QuartzTransformerPlugin } from "../types"
export interface Options {
enableSmartyPants: boolean
}
const defaultOptions: Options = {
enableSmartyPants: true
}
export class GitHubFlavoredMarkdown extends QuartzTransformerPlugin {
name = "GitHubFlavoredMarkdown"
opts: Options
constructor(opts?: Options) {
super()
this.opts = { ...defaultOptions, ...opts }
}
markdownPlugins(): PluggableList {
return this.opts.enableSmartyPants ? [remarkGfm] : [remarkGfm, smartypants]
}
htmlPlugins(): PluggableList {
return []
}
}

View File

@ -0,0 +1,5 @@
export { FrontMatter } from './frontmatter'
export { GitHubFlavoredMarkdown } from './gfm'
export { CreatedModifiedDate } from './lastmod'
export { Katex } from './latex'
export { Description } from './description'

View File

@ -0,0 +1,80 @@
import { PluggableList } from "unified"
import fs from "fs"
import path from 'path'
import { Repository } from "@napi-rs/simple-git"
import { QuartzTransformerPlugin } from "../types"
export interface Options {
priority: ('frontmatter' | 'git' | 'filesystem')[],
}
const defaultOptions: Options = {
priority: ['frontmatter', 'git', 'filesystem']
}
export class CreatedModifiedDate extends QuartzTransformerPlugin {
name = "CreatedModifiedDate"
opts: Options
constructor(opts?: Options) {
super()
this.opts = {
...defaultOptions,
...opts,
}
}
markdownPlugins(): PluggableList {
return [
() => {
let repo: Repository | undefined = undefined
return async (_tree, file) => {
let created: undefined | Date = undefined
let modified: undefined | Date = undefined
let published: undefined | Date = undefined
const fp = path.join(file.cwd, file.data.filePath as string)
for (const source of this.opts.priority) {
if (source === "filesystem") {
const st = await fs.promises.stat(fp)
created ||= new Date(st.birthtimeMs)
modified ||= new Date(st.mtimeMs)
} else if (source === "frontmatter" && file.data.frontmatter) {
created ||= file.data.frontmatter.date
modified ||= file.data.frontmatter.lastmod
modified ||= file.data.frontmatter["last-modified"]
published ||= file.data.frontmatter.publishDate
} else if (source === "git") {
console.log(file)
if (!repo) {
repo = new Repository(file.cwd)
}
modified ||= new Date(await repo.getFileLatestModifiedDateAsync(fp))
}
}
file.data.dates = {
created: created ?? new Date(),
modified: modified ?? new Date(),
published: published ?? new Date()
}
}
}
]
}
htmlPlugins(): PluggableList {
return []
}
}
declare module 'vfile' {
interface DataMap {
dates: {
created: Date
modified: Date
published: Date
}
}
}

View File

@ -0,0 +1,34 @@
import { PluggableList } from "unified"
import remarkMath from "remark-math"
import rehypeKatex from 'rehype-katex'
import { StaticResources } from "../../resources"
import { QuartzTransformerPlugin } from "../types"
export class Katex extends QuartzTransformerPlugin {
name = "Katex"
markdownPlugins(): PluggableList {
return [remarkMath]
}
htmlPlugins(): PluggableList {
return [
[rehypeKatex, {
output: 'html',
}]
]
}
externalResources: Partial<StaticResources> = {
css: [
// base css
"https://cdn.jsdelivr.net/npm/katex@0.16.0/dist/katex.min.css",
],
js: [
{
// fix copy behaviour: https://github.com/KaTeX/KaTeX/blob/main/contrib/copy-tex/README.md
src: "https://cdn.jsdelivr.net/npm/katex@0.16.7/dist/contrib/copy-tex.min.js",
loadTime: "afterDOMReady"
}
]
}
}

38
quartz/plugins/types.ts Normal file
View File

@ -0,0 +1,38 @@
import { PluggableList } from "unified"
import { StaticResources } from "../resources"
import { ProcessedContent } from "./vfile"
export abstract class QuartzTransformerPlugin {
abstract name: string
abstract markdownPlugins(): PluggableList
abstract htmlPlugins(): PluggableList
externalResources?: Partial<StaticResources>
}
export abstract class QuartzFilterPlugin {
abstract name: string
abstract shouldPublish(content: ProcessedContent): boolean
}
export interface EmitOptions {
// meta
title: string
description: string
slug: string
ext: `.${string}`
// rendering related
content: string
}
export type EmitCallback = (data: EmitOptions) => Promise<void>
export abstract class QuartzEmitterPlugin {
abstract name: string
abstract emit(content: ProcessedContent[], emitCallback: EmitCallback): Promise<string[]>
}
export interface PluginTypes {
transformers: QuartzTransformerPlugin[],
filters: QuartzFilterPlugin[],
emitters: QuartzEmitterPlugin[],
}

5
quartz/plugins/vfile.ts Normal file
View File

@ -0,0 +1,5 @@
import { Node } from 'hast'
import { Data, VFile } from 'vfile/lib'
export type QuartzPluginData = Data
export type ProcessedContent = [Node<QuartzPluginData>, VFile]

View File

View File

View File

@ -0,0 +1,58 @@
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import { Processor, unified } from "unified"
import { Root as MDRoot } from 'remark-parse/lib'
import { Root as HTMLRoot } from 'hast'
import { ProcessedContent } from '../plugins/vfile'
import { PerfTimer } from '../perf'
import { read } from 'to-vfile'
import { pathToSlug } from '../path'
import path from 'path'
import { QuartzTransformerPlugin } from '../plugins/types'
export type QuartzProcessor = Processor<MDRoot, HTMLRoot, void>
export function createProcessor(transformers: QuartzTransformerPlugin[]): any {
// base Markdown -> MD AST
let processor = unified().use(remarkParse)
// MD AST -> MD AST transforms
for (const plugin of transformers) {
processor = processor.use(plugin.markdownPlugins())
}
// MD AST -> HTML AST
processor = processor.use(remarkRehype, { allowDangerousHtml: true })
// HTML AST -> HTML AST transforms
for (const plugin of transformers) {
processor = processor.use(plugin.htmlPlugins())
}
return processor
}
export async function parseMarkdown(processor: QuartzProcessor, baseDir: string, fps: string[], verbose: boolean): Promise<ProcessedContent[]> {
const perf = new PerfTimer()
const res: ProcessedContent[] = []
for (const fp of fps) {
const file = await read(fp)
// base data properties that plugins may use
file.data.slug = pathToSlug(path.relative(baseDir, file.path))
file.data.filePath = fp
const ast = processor.parse(file)
res.push([await processor.run(ast, file), file])
if (verbose) {
console.log(`[process] ${fp} -> ${file.data.slug}`)
}
}
if (verbose) {
console.log(`Parsed and transformed ${res.length} Markdown files in ${perf.timeSince()}`)
}
return res
}

9
quartz/resources.ts Normal file
View File

@ -0,0 +1,9 @@
export interface JSResource {
src: string
loadTime: 'beforeDOMReady' | 'afterDOMReady'
}
export interface StaticResources {
css: string[],
js: JSResource[]
}

BIN
quartz/static/icon.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 17 KiB

1
tsconfig.tsbuildinfo Normal file

File diff suppressed because one or more lines are too long