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>