Build script and security

[badlydrawnrob]

Explaining some of the build problems

You'll need to reference some (or all) of these problems in the advanced tutorial for Anki Themes) — especially the "Github dependencies" and "NPM commands" which should be to-the-point and leave no need for thinking. Remember to hide complexity when writing the docs.

• Anki Build Documentation
• Advanced tutorial on building an Anki Theme
• Semantic versioning (and breaking changes)

The Pandoc build script is a little hard to remember:

The Pandoc documentation is pretty verbose, and I struggle with it. I also want to be aware of security concerns with NPM such as here.

1. Output a standalone file
2. Using a template file --template=./source/pandoc/template.html (you can use variables also)
3. By default Pandoc outputs a fragment ...
   • Use the -s or --standalone flag to output a HTML document.
4. To include a custom CSS file (or many), use -c or --css flag!
5. --embed-resources: a standalone document with no external dependencies?
6. Tidy up build scripts? #24 (make things simpler?)7.

NPM commands: Updating your packages

npm can install and run your "scripts".
npx seems to allow you to run CLI commands locally (like this website builder).
I tend towards installing packages locally (not globally)

⚠️ Neither npm update, nor npm install <package> will update to the latest version if you're using ~ or ^ semver ranges!!! Why? Read on ...

🏆 You can specify the @major version with npm install. Alternatively, you must change package.json dependency version first, then npm update to that version. Can be done programatically or manually.

1. Dev dependencies currently updating range only (patch/minor)
   • View npm outdated for regular packages (it won't show GitHub dependancies) and npm update (why won't it update to latest version?)
   • View the Change Log before updating to a major version!
   • npm list --depth 1 will list package dependencies (1 level deep)
2. More on NPM Dependencies and scripts

Such a lot of reading, for such a simple thing 🤬😩

Github dependencies: It get's worse!

GitHub repositories that are dependencies don't update at all!! 😔

Make sure you change the #commit-number on the end of the dependency url. You'll also need to explicitly update the package npm update print-first-css.

Use a makefile and watch changes?

An interesting approach to auto-load changes for .less files in this article.

---

I think I was using the Marked App to compile the specimen.md and styleguide.md files:

You can view the original .md files here

1. Adding the print-first-markdown css file to the app
2. Using it with yaml code Marked Style: print-first-markdown.
3. Marked App uses highlight.js to render code blocks