Merge pull request #46 from olafurpg/lint

Report warnings when linking to non-existing sections

docs/readme.md

@@ -11,26 +11,31 @@ part of your build. Distinguishing features of Vork include:
   regular Scala programs making code examples copy-paste friendly.
 - [good error messages](#good-error-messages): compile errors and crashes are
   reported with positions of the original markdown source.
+- [link hygiene](#link-hygiene): compile errors and crashes are reported with
+  positions of the original markdown source.
 - variable injection: instead of hardcoding constants, use variables like
   `@@VERSION@` to make sure the documentation remains up-to-date.
 - extensible: library APIs expose hooks to customize rendering of code fences.
 
-<!-- TOC -->
-
-- [Vork: markdown worksheets](#vork-markdown-worksheets)
-  - [Quickstart](#quickstart)
-    - [Command-line](#command-line)
-    - [Library](#library)
-  - [Modifiers](#modifiers)
-    - [Default](#default)
-    - [Fail](#fail)
-    - [Crash](#crash)
-    - [Passthrough](#passthrough)
-  - [Key features](#key-features)
-    - [Performance](#performance)
-    - [Good error messages](#good-error-messages)
-    - [Script semantics](#script-semantics)
-  - [Team](#team)
+Table of contents:
+
+<!-- TOC depthFrom:2 -->
+
+- [Quickstart](#quickstart)
+  - [Library](#library)
+  - [Command-line](#command-line)
+- [Modifiers](#modifiers)
+  - [Default](#default)
+  - [Fail](#fail)
+  - [Crash](#crash)
+  - [Passthrough](#passthrough)
+- [Key features](#key-features)
+  - [Performance](#performance)
+  - [Good error messages](#good-error-messages)
+  - [Link hygiene](#link-hygiene)
+  - [Script semantics](#script-semantics)
+- [Team](#team)
+- [--help](#--help)
 
 <!-- /TOC -->
 
@@ -81,17 +86,6 @@ List(x, x)
 Observe that `MY_VERSION` has been replaced with `1.0.0` and that the
 `scala vork` code fence has been interpreted by the Scala compiler.
 
-### Command-line
-
-First, install the
-[coursier command-line interface](https://github.com/coursier/coursier/#command-line).
-
-```
-$ coursier launch com.geirsson:vork_2.12:@VERSION@ -- --site.MY_VERSION 1.0.0
-info: Compiling docs/readme.md
-info:   done => out/readme.md (120 ms)
-```
-
 ### Library
 
 Add the following dependency to your build
@@ -117,6 +111,29 @@ object Website {
 }
 ```
 
+Consult the Vork
+[documentation](https://www.javadoc.io/doc/com.geirsson/vork_2.12/0.2.0) to
+learn more how to use the library API. Note that code in the package
+`vork.internal` is subject to binary and source breaking changes between any
+release, including PATCH versions.
+
+### Command-line
+
+First, install the
+[coursier command-line interface](https://github.com/coursier/coursier/#command-line).
+Then run the following command:
+
+```
+$ coursier launch com.geirsson:vork_2.12:@VERSION@ -- --site.MY_VERSION 1.0.0
+info: Compiling docs/readme.md
+info:   done => out/readme.md (120 ms)
+```
+
+It's possible to customize the input and output directory with `--in` and
+`--out`. There is also a `--watch` flag to watch for file changes and
+incrementally re-generate pages on file save providing fast feedback while
+Consult [`--help`](#--help) to learn more about the command-line interface.
+
 ## Modifiers
 
 Vorks supports several modifiers to control the output of code fences.
@@ -185,8 +202,8 @@ $table
 
 ### Performance
 
-Vork is designed to provide a tight edit/render/preview feedback loop. Vork
-achieves good performance through
+Vork is designed to provide a tight edit/render/preview feedback loop while
+writing documentation. Vork achieves good performance through
 
 - [script semantics](#script-semantics): each markdown file compiles into a
   single Scala program that executes in one run.
@@ -199,7 +216,19 @@ achieves good performance through
 
 ### Good error messages
 
-Vork tries to report helpful error messages when things go wrong
+Vork tries to report helpful error messages when things go wrong. Here below,
+the program that is supposed to compile successfully but it has a type error so
+the build is stopped with an error message from the Scala compiler.
+
+````scala vork:vork:crash
+```scala vork
+val typeError: Int = "should be int"
+```
+````
+
+Here below, the programs are supposed to fail due to the `fail` and `crash`
+modifiers but they succeed so the build is stopped with an error message from
+Vork.
 
 ````scala vork:vork:crash
 ```scala vork:fail
@@ -210,6 +239,26 @@ val noCrash = "success"
 ```
 ````
 
+Observe that positions of the reported diagnostics point to line numbers and
+columns in the original markdown document. Internally, Vork instruments code
+fences to extract metadata like variable types and runtime values. Positions of
+error messages in the instrumented code are translated into positions in the
+markdown document.
+
+### Link hygiene
+
+Docs get quickly out date, in particular links to different sections. After
+generating a site, Vork analyzes links for references to non-existent sections.
+For the example below, Vork reports a warning that the `doesnotexist` link is
+invalid.
+
+```scala vork:vork:crash
+# My title
+
+Link to [my title](#my-title).
+Link to [old section](#doesnotexist).
+```
+
 ### Script semantics
 
 Vork interprets code fences as normal Scala programs instead of as if they're
@@ -250,3 +299,11 @@ The current maintainers (people who can merge pull requests) are:
 - Ólafur Páll Geirsson - [`@olafurpg`](https://github.com/olafurpg)
 
 Contributions are welcome!
+
+## --help
+
+````scala vork:passthrough
+println("```")
+println(vork.internal.cli.Settings.help.helpMessage(80))
+println("```")
+````