ggrossetie / antora-site-generator-lunr Goto Github PK

An Antora's site generator that produces a Lunr index

License: MIT License

JavaScript 93.79% Dockerfile 6.21%

antora-site-generator-lunr's Introduction

ℹ️ Information ℹ️

If you are using Antora 3, you should use the Antora Lunr extension (package: @antora/lunr-extension), which is an official Antora project.

This repository will go into maintenance mode for users who have not yet transitioned from Antora 2 to Antora 3. After some time, the repository will be archived.

Antora Site Generator With Lunr

This site generator is a copy of the default site generator that in addition produces a Lunr index that can be used in your documentation UI. Lunr provides a great search experience in your documentation site without the need for external, server-side, search services.

Antora is a modular static site generator designed for creating documentation sites from AsciiDoc documents. Its site generator pipeline aggregates documents from versioned content repositories and processes them using Asciidoctor.

Usage

Install the site generator. Open a terminal and type:

$ npm i -g antora-site-generator-lunr

When generating your documentation site, use the --generator option:

$ DOCSEARCH_ENABLED=true DOCSEARCH_ENGINE=lunr NODE_PATH="$(npm -g root)" antora --generator antora-site-generator-lunr site.yml

NOTE: The NODE_PATH assignment is necessary to ensure Antora can locate node modules install globally. Depending on your environment, you may find that this assignment is unnecessary. If you've installed Antora globally using Yarn, you may need to add "$(yarn global dir)/node_modules" to the NODE_PATH environment variable instead.

Please read the documentation to enable the search component in your documentation UI.

Using the Docker image

The Docker image is built upon the Antora's official Docker image and should be used as a replacement. For example, instead of running:

$ docker run -u $(id -u) -v $PWD:/antora:Z --rm -t antora/antora:2.3.4 antora-playbook.yml

You will run:

$ docker run -u $(id -u) -v $PWD:/antora:Z --rm -t ggrossetie/antora-lunr antora-playbook.yml

The image sets DOCSEARCH_ENABLED=true and DOCSEARCH_ENGINE=lunr environment variables. When executing docker run, you can overwrite any variable defined in the image. For example:

$ docker run --env DOCSEARCH_ENABLED=false # ...

Moreover, the site generator is automatically configured on the antora command (i.e. --generator antora-site-generator-lunr).

Upgrading

When installing this generator globally (i.e., npm i -g), it also installs a private copy of Antora (minus the CLI). Thus, to upgrade the copy of Antora this site generator uses, you need to reinstall this package. Upgrading Antora alone isn't sufficient.

To upgrade this site generator and Antora, open a terminal and type the following commands:

$ npm uninstall -g antora-site-generator-lunr @antora/cli @antora/site-generator-default

$ npm i -g antora-site-generator-lunr @antora/cli @antora/site-generator-default

These commands ensure you have the latest version of both the site generator and Antora regardless of whether you're using this site generator.

antora-site-generator-lunr's People

Contributors

Stargazers

Watchers

Forkers

mojavelinux danyill synesthesia coliss86 lobokie adito5393 eastuni op-ted

antora-site-generator-lunr's Issues

using antora-site-generator-lunr with Antora 3.0.0 (currently alpha)

I did some experiments with Antora 3.0.0-alpha.7 and this site generator.

I was unable to make it work Antora 3.0.0-alpha.8+ due to API changes in Antora.

TL;DR: works after using some "force" - thanks for providing the plugin!

I needed to update the dependencies to use the 3.x version instead of 2.x using resolutions (see package.json here).

NOTE: The "resolutions" functionality in package.json will work in yarn only.

This is just a note in case someone wants to try something similar.

wrong HTML for image from other module

.npm-global/lib64
├── @antora/[email protected]
├── @antora/[email protected]
└── [email protected]

// modules/ROOT/pages/index.adoc
image::Doc:diagram/doc.png[Diagram from module Doc]

Wrong HTML by [email protected]:

<img src="Doc:diagram/doc.png" alt="Diagram from module Doc">

Correct HTML by @antora/[email protected]:

<img src="Doc/_images/diagram/doc.png" alt="Diagram from module Doc">

Use optionalDependencies to be less tightly coupled to a specific version of Antora

We can use https://gitlab.com/antora/xref-validator/-/blob/master/package.json as an example

Upgrade to Antora 2.2

TypeError: contentCatalog.exportToModel is not a function

I get an error when using the antora-site-generator-lunr v0.5.0. Without the option --generator antora-site-generator-lunr Antora works fine. I followed the installation instructions and I’m using Antora 2.3.3 with the default UI. Before upgrading from Antora 2.2 and antora-site-generator-lunr v0.3.0 everything was working as expected.

Update: It seems that the version 0.5.0 is the problem. Antora 2.3.3 with antora-site-generator-lunr 0.3.0 is working.

Here’s the stacktrace:

$ CI=1 DOCSEARCH_ENABLED=true DOCSEARCH_ENGINE=lunr npx antora playbook-dev.yml --generator antora-site-generator-lunr --stacktrace
TypeError: contentCatalog.exportToModel is not a function
    at buildBaseUiModel (/builds/abc/def/ghi/antora.playbook/node_modules/@antora/page-composer/lib/build-ui-model.js:10:46)
    at createPageComposer (/builds/abc/def/ghi/antora.playbook/node_modules/@antora/page-composer/lib/create-page-composer.js:45:37)
    at generateSite (/builds/abc/def/ghi/antora.playbook/node_modules/antora-site-generator-lunr/lib/generate-site.js:25:23)
    at async run (/builds/abc/def/ghi/antora.playbook/node_modules/@antora/cli/lib/cli.js:17:21)

site.url missing from generated index

In version 2.3.3 the index contains the correct site.url string. In the latest version its missing. Im not sure if this has to do with antora or the site generator.

Works when you install using the 0.4.0 tag

Working in version 2.3.3

window.antoraLunr.init({"index":{"version":"2.3.3","fields":["title","name","text","component"],"fieldVectors":[["title/https://opensource.suse.com/doc-susemanager/suse-manager/common_gfdl1.2_i.html"

Broken in 2.3.8:

window.antoraLunr.init({"index":{"version":"2.3.8","fields":["title","name","text","component"],"fieldVectors":[["title//suse-manager/common_gfdl1.2_i.html"

Cannot install the package

When I following the install instructions, I receive the following error:

npm ERR! code E404
npm ERR! 404 Not Found: antora-site-generator-lunr@latest

Can you suggest a fix please?

Some times we get a TypeError: Cannot read property 'length' of undefined

We have included Antora with the antora-site-generator-lunr in our CI/CD pipeline. We see a flapping behavior always with the same error message in the same git repository like this here:

#!/bin/sh -eo pipefail
npm i -g antora-site-generator-lunr
DOCSEARCH_ENABLED=true DOCSEARCH_ENGINE=lunr NODE_PATH="$(npm -g root)" antora --generator antora-site-generator-lunr --stacktrace generate antora-playbook.yml

+ [email protected]
added 254 packages from 210 contributors in 11.703s
Error: Unknown TypeError: See cause (url: https://github.com/OpenNMS/opennms-js.git)
    at transformGitCloneError (/usr/local/lib/node_modules/antora-site-generator-lunr/node_modules/@antora/content-aggregator/lib/aggregate-content.js:794:22)
    at git.clone.then.then.catch (/usr/local/lib/node_modules/antora-site-generator-lunr/node_modules/@antora/content-aggregator/lib/aggregate-content.js:184:17)
Caused by: TypeError: Cannot read property 'length' of undefined
    at Inflate.push (/usr/local/lib/node_modules/antora-site-generator-lunr/node_modules/pako/lib/inflate.js:218:30)
    at listpack (/usr/local/lib/node_modules/antora-site-generator-lunr/node_modules/isomorphic-git/dist/for-node/isomorphic-git/index.js:3230:16)

Exited with code exit status 1

CircleCI received exit code 1

A manual re-run fixes the problem and it seems to us very hard to reproduce. Do you have any hints on how to debug or investigate this problem?

We use it in an open-source library and everything is in public. Here is the error message from the build fail. We running with Antora 2.3.4.

Thank you in advance

Possible limit to number of pages lunr can process

Hi I am building an antora site with perhaps > 1100 pages.

Not sure if this is helpful or if I really am pushing it all tar too far.

  <--- Last few GCs --->
  
  [4648:00000155E7153AC0]   251886 ms: Scavenge 2044.0 (2052.1) -> 2043.3 (2053.1) MB, 20.8 / 0.0 ms  (average mu = 0.229, current mu = 0.189) allocation failure 
  [4648:00000155E7153AC0]   255746 ms: Mark-sweep (reduce) 2044.8 (2057.1) -> 2043.8 (2058.3) MB, 3848.7 / 0.0 ms  (+ 0.1 ms in 23 steps since start of marking, biggest step 0.0 ms, walltime since start of marking 3859 ms) (average mu = 0.175, current mu = 

FATAL warning : Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

 1: 00007FF74AD41DDF napi_wrap+109135
   2: 00007FF74ACE6D06 v8::internal::OrderedHashTable<v8::internal::OrderedHashSet,1>::NumberOfElementsOffset+33350
   3: 00007FF74ACE7AD6 node::OnFatalError+294
   4: 00007FF74B5B64CE v8::Isolate::ReportExternalAllocationLimitReached+94
   5: 00007FF74B59B31D v8::SharedArrayBuffer::Externalize+781
   6: 00007FF74B44574C v8::internal::Heap::EphemeronKeyWriteBarrierFromCode+1516
   7: 00007FF74B450AAA v8::internal::Heap::ProtectUnprotectedMemoryChunks+1258
   8: 00007FF74B44DC59 v8::internal::Heap::PageFlagsAreConsistent+2457
   9: 00007FF74B4427F1 v8::internal::Heap::CollectGarbage+2033
  10: 00007FF74B4409F5 v8::internal::Heap::AllocateExternalBackingStore+1365
  11: 00007FF74B460F17 v8::internal::Factory::NewFillerObject+183
  12: 00007FF74B18E731 v8::internal::interpreter::JumpTableTargetOffsets::iterator::operator=+1409
  13: 00007FF74B63F01D v8::internal::SetupIsolateDelegate::SetupHeap+463949
  14: 00007FF74B63FF97 v8::internal::SetupIsolateDelegate::SetupHeap+467911
  15: 000002CF2A9366B8