Some doc touchups

- Add missing .md extension to some links
- Add talk from CNCF London
- Various small edits

Signed-off-by: Anders Eknert <anders@styra.com>

README.md

@@ -162,7 +162,7 @@ The following rules are currently available:
 By default, all rules are currently **enabled**.
 
 If you'd like to see more rules, please [open an issue](https://github.com/StyraInc/regal/issues) for your feature
-request, or better yet, submit a PR! See the [custom rules](/docs/custom-rules) page for more information on how to
+request, or better yet, submit a PR! See the [custom rules](/docs/custom-rules.md) page for more information on how to
 develop your own rules, for yourself or for inclusion in Regal.
 
 ## Configuration
@@ -255,11 +255,19 @@ Note that at this point in time, Regal only considers the line following the ign
 entire blocks of code (like rules, or even packages). See [configuration](#configuration) if you want to ignore certain
 rules altogether.
 
-## Documentation
+## Resources
 
-- [Custom Rules](/docs/custom-rules) describes how to develop your own rules
-- [Development](/docs/development) for info about how to hack on Regal itself
-- [Rego Style Guide](/docs/rego-style-guide) contains notes on implementing the [Rego Style Guide](https://github.com/StyraInc/rego-style-guide) rules
+### Documentation
+
+- [Custom Rules](/docs/custom-rules.md) describes how to develop your own rules
+- [Development](/docs/development.md) for info about how to hack on Regal itself
+- [Rego Style Guide](/docs/rego-style-guide.md) contains notes on implementing the
+  [Rego Style Guide](https://github.com/StyraInc/rego-style-guide) rules
+
+### Talks
+
+[Regal the Rego Linter](https://www.youtube.com/watch?v=Xx8npd2TQJ0&t=2567s), CNCF London meetup, June 2023
+[![Regal the Rego Linter](docs/assets/regal_cncf_london.png)](https://www.youtube.com/watch?v=Xx8npd2TQJ0&t=2567s)
 
 ## Status
 
@@ -271,7 +279,7 @@ Regal is currently in beta. End-users should not expect any drastic changes, but
 - [ ] Add `custom` category for built-in "custom", or customizable rules, to enforce things like naming conventions
 - [ ] Simplify custom rules authoring by providing command for scaffolding
 - [ ] Improvements to assist writing rules that can't be enforced using the AST alone
-- [ ] Make more rules consider nesting
+- [ ] Make more rules consider nested AST nodes
 - [ ] GitHub Action
 - [ ] VS Code extension
 

docs/custom-rules.md

@@ -10,9 +10,10 @@ to a Rego file, or a directory containing Rego files and potentially data (JSON
 
 ## Developing Rules
 
-Regal rules works primarily on the abstract syntax tree (AST) as parsed by OPA, with a few custom additions. The AST of
-each policy scanned will be provided as input to the linter policies, and additional data useful in the context of
-linting, as well as some purpose-built custom functions are made available in any Regal policy.
+Regal rules works primarily on the [abstract syntax tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) (AST) as
+parsed by OPA, with a few custom additions. The AST of each policy scanned will be provided as input to the linter
+policies, and additional data useful in the context of linting, as well as some purpose-built custom functions are made
+available in any Regal policy.
 
 If we were to write the simplest policy possible, and parse it using `opa parse`, it would contain nothing but a package
 declaration:
@@ -86,20 +87,20 @@ import data.regal.result
 report contains violation if {
     config.for_rule(rego.metadata.rule()).level != "ignore"
 
-	not acme_corp_package
-	not system_log_package
+    not acme_corp_package
+    not system_log_package
 
-	violation := result.fail(rego.metadata.rule(), result.location(input["package"].path[1]))
+    violation := result.fail(rego.metadata.rule(), result.location(input["package"].path[1]))
 }
 
 acme_corp_package if {
-	input["package"].path[1].value == "acme"
-	input["package"].path[2].value == "corp"
+    input["package"].path[1].value == "acme"
+    input["package"].path[2].value == "corp"
 }
 
 system_log_package if {
-	input["package"].path[1].value == "system"
-	input["package"].path[2].value == "log"
+    input["package"].path[1].value == "system"
+    input["package"].path[2].value == "log"
 }
 ```
 
@@ -130,7 +131,7 @@ custom rules:
 
 - `regal parse` works similarly to `opa parse`, but will always output JSON and include location information, and any
   additional data added to the AST by Regal.
-- `regal test` works like `opa test`
+- `regal test` works like `opa test`, but aware of any custom Regal additions. Use this to test custom linter rules.
 
 Given we want to test `p.rego` against the available set of rules, we can have OPA parse it and pipe the output
 to `opa eval` for evaluation: