format: update format and links

Makefile

@@ -27,7 +27,6 @@ EDN-FILES := $(wildcard *.edn)
 
 pre-commit-check: lint
 
-
 lint:  ## Run MegaLinter with custom configuration (node.js required)
 	$(info --------- MegaLinter Runner ---------)
 	npx mega-linter-runner --flavor documentation --release beta --env "'MEGALINTER_CONFIG=.github/config/megalinter.yaml'" --remove-container

README.md

@@ -1,3 +1,5 @@
+# Practicalli Clojure
+
 ```none
 ██████╗ ██████╗  █████╗  ██████╗████████╗██╗ ██████╗ █████╗ ██╗     ██╗     ██╗
 ██╔══██╗██╔══██╗██╔══██╗██╔════╝╚══██╔══╝██║██╔════╝██╔══██╗██║     ██║     ██║
@@ -17,6 +19,7 @@
 ## Book status
 
 [![MegaLinter](https://github.com/practicalli/clojure/actions/workflows/megalinter.yaml/badge.svg)](https://github.com/practicalli/clojure/actions/workflows/megalinter.yaml)[![Publish Book](https://github.com/practicalli/clojure/actions/workflows/publish-book.yaml/badge.svg)](https://github.com/practicalli/clojure/actions/workflows/publish-book.yaml)
+[![Publish Book](https://github.com/practicalli/clojure/actions/workflows/publish-book.yaml/badge.svg)](https://github.com/practicalli/clojure/actions/workflows/publish-book.yaml)
 [![pages-build-deployment](https://github.com/practicalli/clojure/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/practicalli/clojure/actions/workflows/pages/pages-build-deployment)
 
 [![Ideas & Issues](https://img.shields.io/github/issues/practicalli/clojure?label=content%20ideas%20and%20issues&logoColor=green&style=for-the-badge)](https://github.com/practicalli/clojure/issues)
@@ -25,15 +28,13 @@
 ![GitHub commit activity](https://img.shields.io/github/commit-activity/m/practicalli/clojure?style=for-the-badge)
 ![GitHub contributors](https://img.shields.io/github/contributors/practicalli/clojure?style=for-the-badge&label=github%20contributors)
 
-
 ## Creative commons license
 
 <div style="width:95%; margin:auto;">
   <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-sa/4.0/88x31.png" /></a>
   This work is licensed under a Creative Commons Attribution 4.0 ShareAlike License (including images & stylesheets).
 </div>
 
-
 ## Contributing
 
 Issues and pull requests are most welcome.  Please detail issues as much as you can.  Pull requests are simpler to work with when they are specific to a page or at most a section.  The smaller the change the quicker it is to review and merge.
@@ -47,7 +48,6 @@ Please [see the detailed contributing section of the book](contributing.html) be
 
 By submitting content ideas and corrections you are agreeing they can be used in this workshop under the [Creative Commons Attribution ShareAlike 4.0 International license](https://creativecommons.org/licenses/by-sa/4.0/).  Attribution will be detailed via [GitHub contributors](https://github.com/practicalli/clojure/graphs/contributors).
 
-
 ## Sponsor Practicalli
 
 [![Sponsor practicalli-john](https://raw.githubusercontent.com/practicalli/graphic-design/live/buttons/practicalli-github-sponsors-button.png)](https://github.com/sponsors/practicalli-john/)
@@ -87,14 +87,19 @@ pip3 install mkdocs-material mkdocs-callouts mkdocs-glightbox mkdocs-git-revisio
 Fork the GitHub repository and clone that fork to your computer,
 
 ```bash
-git clone https://github.com/<your-github-account>/clojure.git
-
+git clone https://github.com/<your-github-account>/<repository>.git
 ```
 
 Run a local server from the root of the cloned project
 
 ```bash
-mkdocs serve
+make docs
 ```
 
 The website will open at <http://localhost:8000>
+
+If making smaller changes, then only rebuild the content that changes, speeding up the local development process
+```bash
+make docs
+```
+

docs/introduction/contributing.md

@@ -1,7 +1,5 @@
 # Contributing to Practicalli
 
-How to effectively contribute to Practicalli Books.
-
 Practicalli books are written in markdown and use MkDocs to generate the published website via a GitHub workflow.  MkDocs can also run a local server using the `make docs` target from the `Makefile`
 
 By submitting content ideas and corrections you are agreeing they can be used in this book under the [Creative Commons Attribution ShareAlike 4.0 International license](https://creativecommons.org/licenses/by-sa/4.0/){target=_blank}.  Attribution will be detailed via [GitHub contributors](https://github.com/practicalli/clojure/graphs/contributors){target=_blank}.
@@ -11,6 +9,7 @@ All content and interaction with any persons or systems must be done so with res
 ## Book status
 
 [![MegaLinter](https://github.com/practicalli/clojure/actions/workflows/megalinter.yaml/badge.svg)](https://github.com/practicalli/clojure/actions/workflows/megalinter.yaml)[![Publish Book](https://github.com/practicalli/clojure/actions/workflows/publish-book.yaml/badge.svg)](https://github.com/practicalli/clojure/actions/workflows/publish-book.yaml){target=_blank}
+[![Publish Book](https://github.com/practicalli/clojure/actions/workflows/publish-book.yaml/badge.svg)](https://github.com/practicalli/clojure/actions/workflows/publish-book.yaml){target=_blank}
 [![pages-build-deployment](https://github.com/practicalli/clojure/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/practicalli/clojure/actions/workflows/pages/pages-build-deployment){target=_blank}
 
 [![Ideas & Issues](https://img.shields.io/github/issues/practicalli/clojure-practicalli-content?label=content%20ideas%20and%20issues&logoColor=green&style=for-the-badge)](https://github.com/practicalli/clojure/issues){target=_blank}
@@ -19,13 +18,13 @@ All content and interaction with any persons or systems must be done so with res
 ![GitHub commit activity](https://img.shields.io/github/commit-activity/m/practicalli/clojure?style=for-the-badge)
 ![GitHub contributors](https://img.shields.io/github/contributors/practicalli/clojure?style=for-the-badge&label=github%20contributors)
 
-### Submit and issue or idea
+## Submit and issue or idea
 
 If something doesnt seem quite right or something is missing from the book, please [raise an issue via the GitHub repository](https://github.com/practicalli/clojure/issues){target=_blank} explaining in as much detail as you can.
 
-Raising an issue before creating a pull request will save you and the maintainer time.
+**Raising an issue before creating a pull request will save you and the maintainer time**.
 
-### Considering a Pull request?
+## Considering a Pull request?
 
 Before investing any time in a pull request, please raise an issue explaining the situation.  This can save you and the maintainer time and avoid rejected pull requests.
 

docs/introduction/repl-workflow.md

@@ -46,30 +46,29 @@ The `(comment ,,,)` function wraps code that is only run directly by the develop
 
 Expressions in rich comment blocks can represent how to use the functions that make up the namespace API.  For example, starting/restarting the system, updating the database, etc.  Expressions provide examples of calling functions with typical arguments and make a project more accessible and easier to work with.
 
-!!! EXAMPLE ""
-
-```clojure
-(ns practicalli.gameboard.service)
-
-(defn app-server-start [port] ,,,)
-(defn app-server-start [] ,,,)
-(defn app-server-restart [] ,,,)
-
-(defn -main
-  "Start the service using system components"
-  [& options] ,,,)
-
-(comment
-  (-main)
-  (app-server-start 8888)
-  (app-server-stop)
-  (app-server-restart 8888)
-
-  (System/getenv "PORT")
-  (def environment (System/getenv))
-  (def system-properties (System/getProperties))
-  ) ; End of rich comment block
-```
+!!! EXAMPLE "Clojure Rich Comment to manage a service"
+    ```clojure
+    (ns practicalli.gameboard.service)
+
+    (defn app-server-start [port] ,,,)
+    (defn app-server-start [] ,,,)
+    (defn app-server-restart [] ,,,)
+
+    (defn -main
+      "Start the service using system components"
+      [& options] ,,,)
+
+    (comment
+      (-main)
+      (app-server-start 8888)
+      (app-server-stop)
+      (app-server-restart 8888)
+
+      (System/getenv "PORT")
+      (def environment (System/getenv))
+      (def system-properties (System/getProperties))
+      ) ; End of rich comment block
+    ```
 
 Rich comment blocks are very useful for rapidly iterating over different design decisions by including the same function but with different implementations.  Hide [clj-kondo linter](https://practical.li/clojure/clojure-cli/install/code-analysis.html){target=_blank} warnings for redefined vars (`def`, `defn`) when using this approach.
 
@@ -78,10 +77,10 @@ Rich comment blocks are very useful for rapidly iterating over different design
 #_{:clj-kondo/ignore [:redefined-var]}
 (comment
   (defn value-added-tax []
-    ;; algorithm design - first try)
+    ;; algorithm design - first idea)
 
   (defn value-added-tax []
-    ;; algorithm design - second try)
+    ;; algorithm design - second idea)
 
   ) ;; End of rich comment block
 ```
@@ -118,7 +117,6 @@ Tools to view and navigate code
 
 ![Portal - view and navigate Clojure data and event logs](https://raw.githubusercontent.com/practicalli/graphic-design/live/portal/portal-data-browser-example.png)
 
-
 ## Code Style and idiomatic Clojure
 
 Clojure aware editors should automatically apply formatting that follows the [:globe_with_meridians: Clojure Style guide](https://github.com/bbatsov/clojure-style-guide){target=_blank}.
@@ -186,15 +184,15 @@ Clojure has a number of [:fontawesome-solid-book-open: test runners](https://pra
     Use [:fontawesome-solid-book-open: kaocha test runner](https://practical.li/clojure/testing/test-runners/kaocha-test-runner/){target=_blank} in watch mode to run tests and specification check automatically (when changes are saved)
     ```bash
     clojure -X:test/watch
-```
+    ```
 
 ## Continuous Integration and Deployment
 
 Add a [:fontawesome-solid-book-open: continuous integration service](https://practical.li/clojure/continuous-integration/){target=_blank} to run tests and builds code on every shared commit.  Spin up testable review deployments when commits pushed to a pull request branch, before pushing commits to the main deployment branch, creating an effective pipeline to gain further feedback.
 
-* [:globe_with_meridians: CircleCI](https://practical.li/clojure/continuous-integration/circle-ci/){target=_blank} provides a simple to use service that supports Clojure projects.
-* [:globe_with_meridians: GitHub Workflows](https://docs.github.com/en/actions/using-workflows){target=_blank} and [GitHub actions marketplace](https://github.com/marketplace?type=actions){target=_blank} to quickly build a tailored continuous integration service, e.g. [Setup Clojure GitHub Action](https://github.com/marketplace/actions/setup-clojure){target=_blank}.
-* [:globe_with_meridians: GitLab CI](https://docs.gitlab.com/ee/ci/introduction/index.html){target=_blank}
+- [:globe_with_meridians: CircleCI](https://practical.li/clojure/continuous-integration/circle-ci/){target=_blank} provides a simple to use service that supports Clojure projects.
+- [:globe_with_meridians: GitHub Workflows](https://docs.github.com/en/actions/using-workflows){target=_blank} and [GitHub actions marketplace](https://github.com/marketplace?type=actions){target=_blank} to quickly build a tailored continuous integration service, e.g. [Setup Clojure GitHub Action](https://github.com/marketplace/actions/setup-clojure){target=_blank}.
+- [:globe_with_meridians: GitLab CI](https://docs.gitlab.com/ee/ci/introduction/index.html){target=_blank}
 
 ![Continuous Integration](https://raw.githubusercontent.com/practicalli/graphic-design/live/continuous-integration/continuous-integration-overview.svg)