@patternfly/patternfly-doc-core

Patternfly Documentation Core

Patternfly documentation core contains the base packages needed to build and release the PatternFly org website.

Consuming this repo as a package

Setup

Using this package for your documentation is accomplished in just a few simple steps:

• Run npx @patternfly/patternfly-doc-core@latest setup from the root of your repo. This will:
  • add the documentation core as a dependency in your package
  • add the relevant scripts for using the documentation core to your package scripts
  • create the configuration file for customizing the documentation core
• Install the documentation core using your projects dependency manager, e.g. npm install or yarn install
• Run the initialization script using your script runner, e.g. npm run init:docs or yarn init:docs
  • this will update a Vite config in the documentation so that it can access the files in your repo when running the development server
• Edit the pf-docs.config.mjs file in your project root to point the documentation core to your documentation files

Use

Once setup is complete you can start the dev server with the start script, and create production builds using the build:docs script!

Running this repo directly

Development

The website is built using Astro. Astro looks for .astro or .md files in the src/pages/ directory. Each page is exposed as a route based on its file name.

The src/components/ folder contains Astro and React components that can be used to build the websites pages.

Any static assets, like images, can be placed in the public/ directory.

To define the markdown schema this project uses a typescript based schema known as Zod. Details of how this is integratred into Astro can be found in Astros documentation on content creation using Zod.

Note: When running in dev mode locally on a clean repository, API endpoints will not be available until you run npm run build to generate the API index.

🧞 Commands

All commands are run from the root of the project, from a terminal:

Command	Action
npm install	Installs dependencies
npm run dev	Starts local dev server at localhost:4321
npm run build	Build your production site to ./dist/
npm run preview	Preview your build locally, before deploying
npm run astro ...	Run CLI commands like astro add, astro check
npm run astro -- --help	Get help using the Astro CLI
npm run build:cli	Create a JS build of the documentation core CLI
npm run build:cli:watch	Run the CLI builder in watch mode
npm run build:props	Create a json file of your TsDoc compatible in code documentation