Druxt docs

druxtjs.org

Nuxt frontend and Drupal backend, built with Druxt.

This repository is the source of druxtjs.org, the documentation site for Druxt. It is also a working example of a Druxt site: its pages are Drupal content, rendered by Nuxt.

The site is two applications in one repository. nuxt/ is the frontend. It renders the documentation with Druxt, through DruxtEntity and its wrapper components. drupal/ is the Drupal 11 backend that editors write in.

Get involved

Run the whole site on your machine, frontend and backend together. Pick one of three ways.

Way	You need
Dev container	VS Code with Dev Containers, GitHub Codespaces, or DevPod
mise	mise, and three PHP extensions
By hand	PHP 8.3 or later, Composer and Node 16.20.1

Dev container

Tool	How
VS Code	Clone the repository, open it, then choose Reopen in Container
GitHub Codespaces	On the repository page, open Code and choose Codespaces
DevPod	Click the badge, or run devpod up https://github.com/druxt/druxtjs.org

The container has Node 16.20.1, PHP 8.4, Composer and mise. Creating it runs npm install and npm run setup, so Drupal is running when it opens. Then run npm run dev.

mise

.mise.toml pins Node 16.20.1 and PHP 8.4. PHP needs the gd, pdo_sqlite and sodium extensions.

mise install
npm install
npm run setup
npm run dev

By hand

Install PHP 8.3 or later with the gd, pdo_sqlite and sodium extensions, Composer, and Node 16.20.1. Then run:

npm install
npm run setup
npm run dev

What you get

Command	What it does
npm install	Installs the root tooling and enables the git hooks
npm run setup	Installs Drupal on a throwaway SQLite database, fetches the pinned druxt.js for the API pages, then starts Drupal
npm run dev	Starts the Nuxt dev server against that Drupal. The first run installs the frontend's packages
npm run login	Prints a one-time login link for Drupal

Service	Address
Drupal	http://127.0.0.1:8888, or the next free port. npm run info shows which
Nuxt	http://localhost:3000

npm run setup writes Drupal's address to .env, and npm run dev reads it from there. Setup needs network access, for Composer packages and the pinned documentation on GitHub.

Write documentation

1. Run npm run login, and open the link it prints.
2. In Drupal, go to Content and edit a page, or add one. The layout paragraphs editor builds a page from sections of text, code and images.
3. Save, then reload the page on http://localhost:3000.

Preview, on the edit form, shows unsaved changes. docs/backend.md explains its tabs.

An edit made here is local to this machine's database: it previews and tests the site, and is not how page text is published. See Where changes go for what belongs where.

Editors can also sign in on http://localhost:3000 and see a page's latest draft on its own URL. docs/backend.md covers the workflow and the sign-in.

The Modules, API reference and Components pages come from the druxt.js packages. npm run docs:generate builds them locally, in the pinned druxt.js checkout. It installs and builds druxt.js first, so the first run is slow.

Where changes go

Change	Where it goes
The content model, the editor or the site's settings	Export them with vendor/bin/drush config:export in drupal/, and commit drupal/config/sync/ in a pull request
The frontend	A pull request with the change in nuxt/
The text of a page	Drupal, where editors change it. The database is the source of truth, and page text is not taken as a pull request yet

The site's content is stored in production's database. A local Drupal starts with no pages, and edits in it stay local.

Druxt in the frontend

nuxt/ is a Nuxt 2 app built with Druxt, and it is written to be read as an example of a Druxt site.

What	How
Pages	Each section page resolves its path with the Druxt router, then renders the Drupal page with <DruxtEntity mode="full">.
Wrappers	nuxt/components/druxt/ holds the wrapper components Druxt finds by name. The page is entity/node/DocPageFull.vue, with one component per paragraph type in entity/paragraph/. The rest are fields (field/), layout sections (layout-paragraph/), blocks (block/), block regions (block-region/) and menus (menu/).
Display settings	druxt-schema reads Drupal's view and form displays when the app builds, so the frontend follows the display settings editors change in Drupal.
Layout	druxt-layout-paragraphs renders the page's layout sections.
Header, sidebar and footer	druxt-blocks renders the blocks placed in the druxtjs theme's regions in Drupal. The theme and the site's name and logo come from the druxtjs_org consumer's decoupled settings, read at build by nuxt/modules/decoupled-settings.
UI	nuxt/components/dui/ holds presentational components with no Drupal dependency: code blocks, diagrams, rich text and columns. They will move to the shared Druxt UI library.
Playground	nuxt/components/global/DruxtExample.vue renders any Druxt component under a runtime of its own for the chosen backend (nuxt/utils/druxt-runtime.js), with what it knows about each component in nuxt/utils/live-examples.js. The same card sits on the module and component reference pages.

To change how something looks, find the wrapper name Druxt looked for (the Vue devtools show it), and add a component at the matching path under nuxt/components/druxt/. Component resolution explains the naming.

Deployment

The site runs on Lagoon as one environment, Drupal beside Nuxt. Nuxt serves pre-rendered pages first, and renders live any page it has not stored or that has aged past its time to live. docs/hosting.md covers what a deployment does.

Commands

Command	What it does
npm run setup	Install the backend, then start it
npm run dev	Nuxt dev server against the backend
npm run storybook	Storybook on port 3030, against the backend
npm run start / stop	Start or stop Drupal
npm run info	Where Drupal is, and the versions it runs
npm run login	One-time login link for Drupal
npm run docs:generate	Build the Modules, API reference and Components pages
npm run lint	Every linter except prose
npm run lint:prose	Vale, after npm run lint:prose:install once
npm test	Node tests for the scripts and the frontend's modules

Contributing

See CONTRIBUTING.md for commit messages, checks and what never goes in a file. Open issues and pull requests on druxt/druxtjs.org. docs/backend.md covers page history and previews.

License

MIT