Install and build documentation (beginner and advanced)

[badlydrawnrob]

Simplify this issue down to a single paragraph!!

Change terminology for documentation to easy and hard (so-so isn't very helpful)

• Updating Anki deck #42 (A simple update guide like the release)
• Card data: generating card fields from Markdown (advanced documentation) #97
• Simplify initial README so it's easier to digest
  • Show it, don't say it? Add some gifs like below
  • User pain points. i.e: install without breaking things.
  • Update the professional docs
• Add helper text in card fields #104
  • Stick to the documentation until Anki fixes the way field descriptions work which seems like probably never.
• Build Folder #55 Build folder and basic npm scripts explained in a very simple way
  • I should really only need to make sure this repo is up-to-date with print-first-css etc. I don't have to explain to others unless they're trying to npm run build.
  • Most of the build stuff in print-first-css can be hidden
  • Like a module, some bits are hidden and not extendable.
  • Remember the problems with print-first-css and npm with GitHub repos!
• Other package.json related issues
  • Auto update package.json? #102
  • Remove this line from the package.json? #96
• Can people who need this actually find it? (SEO and inbound) #71
• Issues should probably be handled better
  • Simple enough to not scare kids off
  • Yet thorough enough for my own purposes ...
  • Nice example of a gitbot issue auto-responder

Already thought about ...

• Build script and security notes (Pandoc, Less CSS, Print First CSS)
  • Build passing and other shields (thanks @callmemarcleo)
  • Using semantic versioning properly
  • Be very careful about mustache and JSON formatting using the demo files — especially things like the {{cloze:tag}} demo
  • Demo is useful for now, but involves copying (and slightly editing) the main Card themes in source/themes/demo/...
• Saner internal links? (rather than them scattered in various places)
  • You can actually hover over a link in Visual Studio Code (see below)
  • An online tool (it indexes all Github's links too, not just the README ☹️)
  • ❓Using a link checker tool (Marked App only checks external links)
  • 💩 Or a CLI tool (too many depencies / a ballache to set up)
• Generate PDF

🏆 cmd ⌘ + click: Turns the link blue and takes you to the correct .md page!

Use a CLI tool: 34 bloody dependencies to check your links

test-screen-record.mov

Create a gif how to video with this convertor

[badlydrawnrob]

I removed this for now from the advanced docs but may need to put it back in if people are struggling with dependancies:

5. npm update print-first-css^¶
6. npm update <package> if necessary

¶: Sometimes print-first-css doesn't update properly, so make sure to npm update print-first-css. You might also have to npm audit and npm audit fix to make sure dependencies have no errors. Follow the prompts.

[badlydrawnrob]

Anki theme cards are in source/themes/cards/... but the demo is in source/themes/demo/... folders.

• I've also changed the ★ Key point (code block or image) in the demo .json file:
  • — cloze front
  • — cloze reverse

This allows me to check the CSS styles and mimic the {{cloze::text}} field in Anki app (which is actually the same field in the front and the back card.

With mustache, you need to make sure that the .json file is formatted correctly. For basic html, you don't need to escape the JSON — however, as soon as you have HTML tags that have " " double quotes, you'll need to escape that value or else it will throw the following error:

Use a tool like this one to escape the JSON value.

Furthermore, Anki expects {{ ... }} double quotes only. Mustache allows for {{{ ... }}} triple quotes, or {{& ... }} symbol to make sure that the value DOES NOT GET ESCAPED!

So for the time being, I've copied the front and back templates into a demo/ folder which will handle the mustache templates and .json. I may rip this out completely but it's a bit useful for now.

Without the {{{ triple brackets }}}, you'll see a mess of a result:

[badlydrawnrob]

This is all too overthinky. Keep your target audience and beginners and intermediates and that'll help you scope out what you should be doing. Very, very simple compiler and mostly what you see is what you get. The advanced guys should be able to do it alone anyways.