The hardest part is getting mdocs properties file correctly configured and figuring out how to maintain it. Look in this path after SBT start.
/Users/simon/Code/mdoc_test/myproject-docs/target/scala-3.3.3/resource_managed
There should be an mdoc.properties. I would recommend, copying that file to the resources directory of your mdoc project. Rename it "my.properties". You may then wish to add other properties, according to mdocs documentation. e.g.
js-html-header=<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/[email protected]/cdn/themes/light.css" /><script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/[email protected]/cdn/shoelace-autoloader.js"></script>
In an sbt console,
mdoc --import-map-path importmap.json --property-file-name my.properties.
This should run mdoc and successfully compile the markdown files. If that worked, run this
mdoc --watch --import-map-path importmap.json --property-file-name my.properties
And visit http://localhost:4000/.
This repository is an example of using mdoc to document scala JS projects. It is a rider to this PR;
That PR "works" and is reasonably well tested, but configuring mdoc to use it effectively is almost pathologically tricky. Hence, this repo.
Areas of configuration:
- sbt project settings
- properties file (which is generated by the sbt mdoc plugin). It must be located in a resource directory of the mdoc (NOT the mdoc-js!!! project).
- command line flags
Hint: I strongly recommend checking in some version of the proprties file. You'll always have to generate it for the environment you are running in, but it's so painful to get right, that having a source of correctness available can save significant frustration.
It forms a poor mans package.json and is painful to recreate if lost.