Development discussions (i.e., software architecture and project management) about Antora, the static site generator for making documentation sites based on AsciiDoc.
For this,
yarn is a synonym for npm. yarn used to be notably faster than npm, but npm has caught up and performance is similar-ish.
no typo I can see :-(
Are you building a package for distribution? If not, there is no
packages folder. When I install Antora, all of its packages live under @antora, with this folder structure:$ tree -d @antora/
@antora
├── asciidoc-loader
│ └── lib
│ ├── converter
│ ├── image
│ ├── include
│ ├── util
│ └── xref
├── cli
│ ├── bin
│ └── lib
│ └── commander
├── content-aggregator
│ └── lib
├── content-classifier
│ └── lib
│ └── util
├── document-converter
│ └── lib
├── expand-path-helper
│ └── lib
├── navigation-builder
│ └── lib
├── page-composer
│ └── lib
├── playbook-builder
│ └── lib
│ └── config
├── redirect-producer
│ └── lib
├── site-generator-default
│ └── lib
├── site-mapper
│ └── lib
├── site-publisher
│ └── lib
│ └── providers
│ └── common
└── ui-loader
└── lib
But, I've never published an NPM package before, so I don't know all of the details.
That did populate a number of
node_modules folders:$ find packages -type d -name 'node_modules'
packages/asciidoc-loader/test/fixtures/node_modules
packages/content-aggregator/node_modules
packages/playbook-builder/node_modules
packages/ui-loader/node_modules
packages/page-composer/node_modules
Does your
lerna.json have this line: "npmClient": "yarn",
At least, on the Antora repo.
Then I run
lerna bootstrap, the yarn install happens after the lerna info bootstrap root only line. I think yarn is populating the node_modules folders for each package.
For your new project, do your package folders each contain a
package.json file?
Note that
yarn de-dupes dependencies. If your project's package.json requires package A, and a package in the packages folder also requires A, then only the project node_modules folder gets created for the dependency. Dependencies unique to the package in the packages folder get managed in the per-package node_modules folder.
I have to leave for a while, thanks for your help! I love that article you found, it helps me understand what's going on much better!
I've run into a problem making antora generate pdfs, adapting asciidoctor-pdf.js. Single pages work pretty well, and I've been working to print larger bits by manually constructing pages that include other pages; basically replacing the xrefs in a nav file with includes. This is similar to what the uyuni manager (formerly Suse manager) docs do, although they use asciidoctor-pdf (ruby). The pdfs look pretty good, with page numbers, TOC, index etc. but the internal xrefs don't work! This isn't surprising, since they started out as between-page xrefs. Does anyone have any ideas how to detect and rewrite these links? For instance, do includes leave some trace in the asciidoctor parse tree that could be detected by a tree processor? Can the include processor attach a map of included file name to first included section? Or could it add an anchor for the page start?
@djencks_gitlab do you use https://gitlab.com/antora/antora/blob/master/packages/asciidoc-loader/lib/xref/convert-page-ref.js?
I guess you could use a different strategy if you are running in this "mode"
@Mogztter Yes, so far I'm using the built-in antora xref processing. Basically I'm wondering how to gather the information I'd need to transform what are now intra-document references. Does the parse tree retain indications of inclusions, or do I have to write an include processor and gather that myself during inclusion?
it's probably not enough but you can fetch
includes on the document.catalog: https://github.com/asciidoctor/asciidoctor/blob/194d191f24dd6a069055c903cd7019772cfa988f/lib/asciidoctor/document.rb#L289
I haven't found any information in the accessible parse tree that indicates inclusions happened, so I'm going to try to modify the antora include processor.
I'm really wondering, though, what should happen to links outside the document to other parts of the "original" site? For instance, if each module is glommed into one pdf, what should happen to an xref from one module to another? I guess a starting point would be to link to the published site url for the html page.