Added Storybook to Netlify build to allow relative links from documen…

…tation (plone#5599)

Makefile

@@ -145,8 +145,10 @@ docs-vale: bin/python docs-news  ## Install (once) and run Vale style, grammar,
 
 .PHONY: netlify
 netlify:
-	pip install -r requirements-docs.txt
-	cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) ../$(BUILDDIR)/html
+	pnpm build:registry
+	(cd packages/volto && pnpm build-storybook -o ../../_build/html/storybook)
+	pwd && pip install -r requirements-docs.txt
+	cd $(DOCS_DIR) && pwd && sphinx-build -b html $(ALLSPHINXOPTS) ../$(BUILDDIR)/html
 
 .PHONY: docs-test
 docs-test: docs-clean docs-linkcheckbroken docs-vale  ## Clean docs build, then run linkcheckbroken, vale
@@ -156,7 +158,7 @@ docs-test: docs-clean docs-linkcheckbroken docs-vale  ## Clean docs build, then
 .PHONY: storybook-build
 storybook-build:
 	pnpm build:registry
-	(cd packages/volto && pnpm build-storybook -o ../../docs/_build/storybook)
+	(cd packages/volto && pnpm build-storybook -o ../../docs/_build/html/storybook)
 
 .PHONY: patches
 patches:

docs/source/contributing/documentation.md

@@ -144,3 +144,27 @@ To build the Volto Storybook locally and test your entry, run the following comm
 ```shell
 make storybook-build
 ```
+
+
+(link-to-storybook-entries-from-documentation)=
+
+### Link to Storybook entries from documentation
+
+To hyperlink to Storybook entries from the narrative documentation, you can use one of two syntaxes.
+
+Use HTML syntax to enable hyperlinking in development, within Netlify preview builds, and when the main Plone documenation is updated.
+Hyperlinking in development requires that you run both `make docs-html` and `make storybook-build` commands once, then whenever you update either the narrative documentation or the Storybook.
+
+```html
+<a href="/storybook/index.html?path=/story/edit-widgets-colorpicker--default">color picker widget</a>
+```
+
+<a href="/storybook/index.html?path=/story/edit-widgets-colorpicker--default">color picker widget</a>
+
+Use CommonMark syntax to point only to the main production Plone documentation.
+
+```md
+[color picker widget](https://6.docs.plone.org/storybook/index.html?path=/story/edit-widgets-colorpicker--default)
+```
+
+[color picker widget](https://6.docs.plone.org/storybook/index.html?path=/story/edit-widgets-colorpicker--default)

netlify.toml

@@ -1,5 +1,4 @@
 [build.environment]
   PYTHON_VERSION = "3.8"
-  NODE_VERSION = "16.17.1"
 [build]
   ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF ./docs/"

packages/volto/news/5599.documentation

@@ -0,0 +1 @@
+Enabled hyperlinking from narrative documentation to Storybook entries while developing, in Netlify preview builds, and when deployed to the main production Plone documentation. Documented usage and syntax in {ref}`link-to-storybook-entries-from-documentation`. @stevepiercy