Useful Stuff

These references have been found useful at some stage in preparing the manuals.

  • Github Markdown Syntax Cheatsheet

  • Stop ci building when adding manuals

Add [skip ci] [skip appveyor] at the top of the commit message. This does not stop circleci builds at present, although the build does not result in a beta or master package. It generates an alpha.

  • Including images in PDF made using asciidoctor-pdf

  • Asciidoc Syntax (another reference)

  • Python Stuff

  • Pandoc

Convert all files in a folder using Pandoc and bash:

for f in $(find . -iname '*.md' -type f); do pandoc $f -o ${f%.md}.adoc; done
  • Edit files using sed and bash

  • Creating a thumbnail, linked image

For a smaller thumbnail that is linked to the larger (double-click) image:

image::foo.png["Foo comment",width=550,link="../images/foo.png"]
  • Finding broken links

Under "build the site with antora" Full Linkcheck I see a number of missing links. There are a lot of links to cruiser’s forum which still work. I am trying to find the locations in the text for these. How would one do that?

They are straight html link, right? Just do git grep https://www.cruisersforum.com, that gives you the matches and files. Or use git grep -l which just returns a list of files containing the link.

Rick@Dart MINGW64 ~/documents/github/development/modules/ROOT/pages (main)
$ grep https://www.cruisersforum.com/

and cursor is just blinking. This is using Windows Bash prompt.

grep reads by default from stdin…​ type control-C to get out of this. Then use the correct command git grep which by default searches from current dir.

  • Finding unresolved Antora xrefs

Unresolved xref: links are rendered with a red font in HTML. Such links can be found after making a local build using

$ grep -r "page unresolved" docs
  • Remove execute permissions from files in windows

Windows occasionally adds execute permissions to source files. Although invisible on windows, they are a pain in Linux and MacOS and should be removed using:

git update-index --chmod=-x <file>