docs-antora/README.adoc

   1 = Antora Docs build procedure
   2
   3 :idseparator: -
   4
   5 [source,bash]
   6 ----
   7 $ git clone git://git.evergreen-ils.org/working/Evergreen.git
   8 $ cd Evergreen
   9 $ git checkout collab/blake/LP1848524_antora_ize_docs
  10 ----
  11
  12 First we have to install antora:
  13 Summarized from
  14 https://docs.antora.org/antora/2.1/install/install-antora/
  15
  16 [source,bash]
  17 ----
  18 $ cd docs-antora
  19 # (we want to install into directory as opposed to globally)
  20 $ npm i @antora/cli@2.1 @antora/site-generator-default@2.1
  21 ----
  22
  23
  24 Now, install the ui pre-reqs building
  25 lifted from:
  26 https://docs.antora.org/antora-ui-default/set-up-project/
  27
  28 [source,bash]
  29 ----
  30 $ cd ui
  31 $ npm install
  32 $ gulp --tasks-simple
  33 $ gulp bundle
  34 ----
  35
  36 At this point you should find a file in:
  37
  38 NOTE: build/ui-bundle.zip
  39
  40 Now you can build the website. But you may want to edit the file:
  41
  42 NOTE: docs-antora/site.yml
  43
  44 Because the output folder for the website is defaulted to
  45
  46 NOTE: /var/www/html/prod
  47
  48 And the default web URL is:
  49
  50 NOTE: http://localhost/prod
  51
  52 Build:
  53
  54 [source,bash]
  55 ----
  56 $ cd ..
  57 antora site.yml
  58 ----
  59
  60 If all went well - then you will have the site built in the output folder that was configured in site.yml!
  61
  62 Interesting reading related to Antora and AsciiDoc and AsciiDoctor
  63
  64 NOTE: https://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/
  65
  66 NOTE: https://blog.anoff.io/2019-02-15-antora-first-steps/
  67
  68 NOTE: https://owncloud.org/news/owncloud-docs-migrating-antora-pt-1-2/
  69
  70
  71 == Search stuff
  72
  73 First you need to have ansible installed
  74
  75 NOTE: If you want to manually edit the file, you don't need to install ansible
  76
  77 [source,bash]
  78 ----
  79 $ sudo apt-get -y install ansible
  80 ----
  81
  82 Now, let's run through the antora-lunr procedure:
  83
  84 NOTE: Lifted from the base install notes from the  https://github.com/Mogztter/antora-lunr[ git repo]
  85
  86
  87 [source,bash]
  88 ----
  89 $ ansible-playbook setup_lunr.yml
  90
  91 ----
  92
  93 This should have edited this file: node_modules/@antora/site-generator-default/lib/generate-site.js
  94 as outlined in the git repo notes
  95
  96 Now, install the lunr bits (from docs-antora folder)
  97
  98 [source,bash]
  99 ----
 100 $ npm i antora-lunr
 101 ----
 102
 103 And now, you can re-generate the site but this time with the search box:
 104
 105 [source,bash]
 106 ----
 107 $ DOCSEARCH_ENABLED=true DOCSEARCH_ENGINE=lunr antora site.yml
 108 ----
 109