1 = Antora Docs build procedure
5 == Using generate_docs.pl
7 This tool should perform all of the steps in "Doing it Manually", automatically. This tool requires some command line arguments and also requires some prerequisites.
11 Be sure and have Node installed.
13 see https://github.com/nvm-sh/nvm#installation-and-update[Installing Node]
17 wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash
22 Once Node is installed, follow the Antora prereqs
24 Summarized from https://docs.antora.org/antora/2.3/install/linux-requirements/[Antora pre-reqs]
31 === Run generate_docs.pl
33 This tool does the rest of the work. You will be requried to supply these things:
39 |[URL where html output is expected to be available eg: http//examplesite.org]
42 |[Writable path for staging the antora UI repo and build files, defaults to ./build]
45 |[Path for the generated HTML files, defaults to ./output]
48 |[Antora-UI repository for the built UI, defaults to git://git.evergreen-ils.org/eg-antora.git]
51 |[Version of antora to use for build, defaults to 2.3]
60 $ ./generate_docs.pl \
61 --base-url http//examplesite.org/prod \
62 --tmp-space ../../tmp \
63 --html-output /var/www/html/prod \
64 --antora-ui-repo git://git.evergreen-ils.org/eg-antora.git \
69 NOTE: This tool will create the tmp-space and html-ouput directories if they do not exist. These folders will be erased and re-created with each execution.
73 == Doing it all manually
77 $ git clone git://git.evergreen-ils.org/Evergreen.git
78 $ git clone git://git.evergreen-ils.org/eg-antora.git
82 First we have to install antora:
84 https://docs.antora.org/antora/2.1/install/install-antora/
89 # (we want to install into the local directory as opposed to globally)
90 $ npm install @antora/cli@2.3 @antora/site-generator-default@2.3 antora-lunr antora-site-generator-lunr
94 Now, install the ui pre-reqs building
96 https://docs.antora.org/antora-ui-default/set-up-project/
98 https://github.com/Mogztter/antora-lunr
107 At this point you should find a file in:
109 NOTE: build/ui-bundle.zip
111 Note that if you are using a customized build of antora-ui you will need to include the proper lunr ui components in your local repository. Now you can build the website but you may want to edit the file:
115 Because the output folder for the website is defaulted to
117 NOTE: /var/www/html/prod
119 And the default web URL is:
121 NOTE: http://localhost/prod
127 $ cd ../Evergreen/docs
128 DOCSEARCH_ENABLED=true DOCSEARCH_ENGINE=lunr antora --generator antora-site-generator-lunr site.yml
131 If all went well - then you will have the site built in the output folder that was configured in site.yml!
133 Interesting reading related to Antora and AsciiDoc and AsciiDoctor
135 NOTE: https://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/
137 NOTE: https://blog.anoff.io/2019-02-15-antora-first-steps/
139 NOTE: https://owncloud.org/news/owncloud-docs-migrating-antora-pt-1-2/