Skip to content
This repository has been archived by the owner on Sep 11, 2024. It is now read-only.

whamcloud/vitepress-export-pdf

 
 

Repository files navigation

vitepress-export-pdf

NPM version NPM Downloads GitHub stars

vitepress-export-pdf allows you to export your sites to a PDF file.

Related

Installation

npm install vitepress-export-pdf -D

then add script to your package.json:

{
  "scripts": {
    "export-pdf": "press-export-pdf export [path/to/your/docs]"
  }
}

Then run:

npm run export-pdf

press-export-pdf Command Options

The package provides the press-export-pdf command with the following command line options:

vitepress-export-pdf.png

  • export [sourceDir]: Export your site to a PDF file
    • -c, --config <config>: Set path to config file
    • --outFile <outFile>: Name of output file
    • --outDir <outDir>: Directory of output files
    • --pdfOutlines <pdfOutlines>: Keep PDF outlines/bookmarks(Node >= 18.5.0)
    • --urlOrigin <urlOrigin>: Change the origin of the print url(Option displayHeaderFooter of pdfOptions is true)
    • --debug: Enable debug mode
  • info: Display environment information
  • --help: Display help information
  • --version: Display version information

Config File Options

You can create a new config file, we support the following files:

  • vitepress-pdf.config.ts
  • vitepress-pdf.config.js
  • vitepress-pdf.config.cjs
  • vitepress-pdf.config.mjs
  • .vitepress/vitepress-pdf.config.ts
  • .vitepress/vitepress-pdf.config.js
  • .vitepress/vitepress-pdf.config.cjs
  • .vitepress/vitepress-pdf.config.mjs

In addition, you can also customize the configuration file through --config or -c.

It is recommended to use TS(.vitepress/vitepress-pdf.config.ts) files, which are easy to manage and have friendly code prompts.

ex:

// .vitepress/vitepress-pdf.config.ts
import { defineUserConfig } from 'vitepress-export-pdf'

export default defineUserConfig({
  // ...
})

if you want to use JS files, you can leverage your IDE's intellisense with jsdoc type hints:

/**
 * @type {import('vitepress-export-pdf').UserConfig}
 */
const config = {
  // ...
}

export default config

config options:

  • sorter - function for changing pages order (default undefined)
  • outFile - name of output file (default vitepress-YYMMDD-HHmmss.pdf)
  • outDir - Directory of output files (default package.json file exists in directory)
  • routePatterns - Specify the patterns of files you want to be exported. The patterns are relative to the source directory (default ["/**", "!/404.html"]).Patterns to match Route path using multimatch
  • puppeteerLaunchOptions - Puppeteer launch options object
  • pdfOptions - Valid options to configure PDF generation via Page.pdf() (default { format: 'A4 }), pageNumber and totalPages of headerTemplate and footerTemplate cannot be used because of this reason
  • pdfOutlines - Keep PDF outlines/bookmarks(default true)
  • urlOrigin: Change the origin of the print url(Option displayHeaderFooter of pdfOptions is true) - (How do I change the URL point to the localhost)
  • outlineContainerSelector: Specify an outline container selector.

Examples

A usable example of quick start click here.

Refer to this example for more information,there is a very useful configuration file vitepress-pdf.config.ts

Order of PDF

console.log all the routes in the sort function and assign them to the variable routeOrder as a value. You can adjust the order of printing in the array routeOrder.

import { defineUserConfig } from 'vitepress-export-pdf'

const routeOrder = [
  '/index.html',
  '/guide/what-is-vitepress.html',
  '/guide/getting-started.html',
  '/guide/configuration.html',
  // ...
]

export default defineUserConfig({
  sorter: (pageA, pageB) => {
    const aIndex = routeOrder.findIndex(route => route === pageA.path)
    const bIndex = routeOrder.findIndex(route => route === pageB.path)
    return aIndex - bIndex
  },
})

In order to avoid maintaining two routes, you can read the link fields specified by Nav and Sidebar in the vitepress configuration file by coding, and then sort them. The outline of the code is as follows:

import vitepressConfig from './config'

function extractLinksFromConfig(config: DefaultTheme.Config) {
  const links: string[] = []
  // Some code logic
  return links
}

const links = extractLinksFromConfig(vitepressConfig.themeConfig!)
const routeOrder = [
  '/index.html',
  ...links,
]

The full code is here

Don't export homepage

.vitepress/vitepress-pdf.config.ts add routePatterns:

import { defineUserConfig } from 'vitepress-export-pdf'

export default defineUserConfig({
  routePatterns: ['!/'],
})

Note: ! at the beginning of a pattern will negate the match

PDF print style

Unlike VuePress, VitePress has no customization global style(ex VuePress2.x .vuepress/styles/index.scss) function, but we can customize themes to achieve this.

create the .vitepress/theme/index.ts or .vitepress/theme/index.js file (the "theme entry file").

// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'

// custom CSS
import './style/print.css'

export default {
  // Extending the Default Theme
  ...DefaultTheme,
}

create /style/print.css:

@media print {
  .VPNav,
  .VPLocalNav,
  .VPDocFooter {
    display: none !important;
  }
}

compare-print-style.png

Contributing

  1. Fork it!
  2. Create your feature branch: git checkout -b my-new-feature
  3. Commit your changes: git commit -am 'Add some feature'
  4. Push to the branch: git push origin my-new-feature
  5. Submit a pull request :D

Report Bug

run press-export-pdf info Shows debugging information about the local environment.

License

MIT

Packages

No packages published

Languages

  • TypeScript 97.4%
  • JavaScript 2.6%