brancusi / fulcro-community.github.io

GitHub pages for the community

Source for https://fulcro-community.github.io/ build by https://antora.org/ - see ./antora-playbook.yml.

Whenever we push to this repo:

• the GitHub action invokes antora with the playbook, which fetches docs from this one and additional repos (guides etc)

• the site is built and pushed to the gh-pages branch, GH displays it.

Site structure

The site is composed of multiple separate git repositories - "documentation modules" - included either via git submodules (where the structure of the repo is suitable for that) or explicitly.

What modules are there? Look into ./antora-playbook.yml for what sources we include and then into antora.yml in that repo/directory; the name: there defines the name of the module that you can use to refer to it. As of 3/2021, these are:

• main - this repository itself (see ./modules/ROOT/)

• awesome-fulcro - https://github.com/fulcro-community/awesome-fulcro (as a submodule)

• guides - https://github.com/fulcro-community/guides

Content contributor guide

Content that should be included in the site by Antora needs to have a [specific structure and use correct links.

Antora sees every document source - a github repo, in our case - as a "doc component" and requires that it has a top-level antora.yml that gives the component a name (used in links etc.) and that the Asciidoc content itself is under modules/<module name>/pages/. Each module also may have the default ROOT module - its name in links etc. is left out (i.e. it is ""). Look at the guides module for an example.

• Page meta: The heading of the page must be h1, i.e. a single =. It will then also be used as the <title>. Add :description: <your text> right underneath the heading to provide content for the description meta tag and a preview on social media.

• Links: Links to other pages in the same repository ("doc component"): use xref:<module name>:<page name>.adoc. So if you have modules/my-stuff/pages/index.adoc you link to it via xref:my-stuff:index.adoc. If the module happens to be ROOT then leave it out: xref::<page>. To link to pages in another "componets", just prefix it with the component’s name. Ex.: xref:guides:guide-learning-fulcro:index.adoc. See above for available modules.

• Images: While pages go to the pages/ directory of a module, images should be in its images/ sibling and can be referenced simply by name: image::my-image.jpg[].

Preview locally

Remember to check out submodules first: git submodule update --init --recursive

Make sure that you have cloned all relevant fulcro-community repositories (see Site structure above) into the same parent dir and run ./build-locally.sh to build the site and then a HTTP server to server the resulting directory.

See antora-playbook-local.yml for details.