Link formatting / normalization

.markdownlint.yaml

@@ -1,11 +1,13 @@
 # markdownlint configuration with all properties set to their default value
 # EXCEPT
-# MD052: false
-# MD053: false
 # MD013: false
-# MD043: false
-# MD041: false
 # MD033: false
+# MD034: false
+# MD041: false
+# MD043: false
+# MD052: false
+# MD053: false
+# MD054
 
 # Default state for all rules
 default: true
@@ -161,7 +163,7 @@ MD033: false
   # allowed_elements: []
 
 # MD034/no-bare-urls : Bare URL used : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md034.md
-MD034: true
+MD034: false
 
 # MD035/hr-style : Horizontal rule style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md035.md
 MD035:
@@ -257,18 +259,18 @@ MD053: false
 
 # MD054/link-image-style : Link and image style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md054.md
 MD054:
-  # Allow autolinks
-  autolink: true
-  # Allow inline links and images
+  # Allow autolinks; default: true
+  autolink: false
+  # Allow inline links and images; default: true
   inline: true
   # Allow full reference links and images
   full: true
-  # Allow collapsed reference links and images
-  collapsed: true
-  # Allow shortcut reference links and images
-  shortcut: true
+  # Allow collapsed reference links and images; default: true
+  collapsed: false
+  # Allow shortcut reference links and images; default: true
+  shortcut: false
   # Allow URLs as inline links
-  url_inline: true
+  url_inline: false
 
 # MD055/table-pipe-style : Table pipe style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md055.md
 MD055:

CODE_OF_CONDUCT.md

@@ -75,10 +75,14 @@ Community leaders will follow these Community Impact Guidelines in determining t
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at <https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>.
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available [here][code_of_conduct].
 
-Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][enforcement_ladder].
 
-[homepage]: https://www.contributor-covenant.org
+For answers to common questions about this code of conduct, see the [FAQ][faq]. [Translations][translations] are available.
 
-For answers to common questions about this code of conduct, see the FAQ at <https://www.contributor-covenant.org/faq>. Translations are available at <https://www.contributor-covenant.org/translations>.
+[homepage]: https://www.contributor-covenant.org
+[code_of_conduct]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html
+[enforcement_ladder]: https://github.com/mozilla/diversity
+[faq]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

TODO.md

@@ -14,7 +14,8 @@
 - [ ] review each .md file in turn
 - [ ] create badge refdefs for links to RBE book
 - [ ] pull request to little book of rust books
-- [ ] Consider adding project to <https://goodfirstissue.dev/language/rust>
+- [ ] Consider adding project to [goodfirstissue.dev][goodfirstissue]
+[goodfirstissue]: https://goodfirstissue.dev/language/rust
 - [ ] review GA / GSC - issues with redirects??
 - [ ] incorporate cwd.rs example + any other new examples
 - [ ] finish word index
@@ -27,17 +28,26 @@
 - [ ] license
 - [ ] update thanks
 - [ ] add licenses to thanks page ?
-- [ ] [add page TOC ?](https://github.com/zjp-CN/mdbook-theme) or [alternative](https://github.com/slowsage/mdbook-pagetoc) or [mdbook-toc](https://github.com/badboy/mdbook-toc)
-- [ ] [better search?](https://github.com/ang-zeyu/infisearch)
-- [ ] <https://www.sheshbabu.com/posts/rust-module-system/>
-- [ ] Review <https://github.com/rust-unofficial/awesome-rust> - [ ] already in links.md
-- [ ] Review <https://github.com/rust-unofficial/patterns> - [ ] already in links.md
-- [ ] <https://www.reddit.com/r/rust/comments/15b9rl5/rust_tutorial_that_actually_teaches_rust/>
-- [ ] Link to <https://stevedonovan.github.io/rust-gentle-intro/>
+- [ ] add page TOC ? [mdbook-theme][mdbook-theme]
+[mdbook-theme]: https://github.com/zjp-CN/mdbook-theme
+[alternative][mdbook-pagetoc]
+[mdbook-pagetoc]: https://github.com/slowsage/mdbook-pagetoc
+[mdbook-toc][mdbook-toc]
+[mdbook-toc]: https://github.com/badboy/mdbook-toc
+- [ ] better search? [infisearch][infisearch]
+[infisearch]: https://github.com/ang-zeyu/infisearch
+- [ ] [rust-module-system][rust-module-system]
+[rust-module-system]: https://www.sheshbabu.com/posts/rust-module-system
+- [ ] Review [awesome-rust][awesome-rust]
+[awesome-rust]: https://github.com/rust-unofficial/awesome-rust - already in links.md
+- [ ] Review [rust-unofficial/patterns][rust-unofficial-patterns] [rust-unofficial-patterns]: https://github.com/rust-unofficial/patterns - already in links.md
+- [ ] [rust_tutorial_that_actually_teaches_rust][rust_tutorial_that_actually_teaches_rust] [rust_tutorial_that_actually_teaches_rust]: https://www.reddit.com/r/rust/comments/15b9rl5/rust_tutorial_that_actually_teaches_rust
+- [ ] Link to [rust-gentle-intro][rust-gentle-intro] [rust-gentle-intro]: https://stevedonovan.github.io/rust-gentle-intro
 - [ ] database access: sqlx, seaORM
 - [ ] CI / CD: rust-cache
 - [ ] cargo outdated / audit / license / deny
-- [ ] <https://hoverbear.org/blog/rust-state-machine-pattern/>
+- [ ] [rust-state-machine-pattern][rust-state-machine-pattern]
+[rust-state-machine-pattern]: https://hoverbear.org/blog/rust-state-machine-pattern
 - [ ] review deny.toml
 - [ ] more details in the standard library section
 - [ ] add more to tokio.md
@@ -47,15 +57,15 @@
 - [ ] 'static and Send constraints
 - [ ] I/O
 - [ ] Join, select
-- [ ] <https://tokio.rs/tokio/topics/tracing-next-steps>
-- [ ] <https://ryhl.io/blog/async-what-is-blocking/>
-- [ ] <https://ryhl.io/blog/actors-with-tokio/>
-- [ ] <https://docs.rs/tokio/latest/tokio/sync/mpsc/index.html#communicating-between-sync-and-async-code>
+- [ ] [tracing-next-steps][tracing-next-steps] [tracing-next-steps]: https://tokio.rs/tokio/topics/tracing-next-steps
+- [ ] [async-what-is-blocking][async-what-is-blocking] [async-what-is-blocking]: https://ryhl.io/blog/async-what-is-blocking
+- [ ] [actors-with-tokio][actors-with-tokio] [actors-with-tokio]: https://ryhl.io/blog/actors-with-tokio
+- [ ] [communicating-between-sync-and-async-code][communicating-between-sync-and-async-code] [communicating-between-sync-and-async-code]: https://docs.rs/tokio/latest/tokio/sync/mpsc/index.html#communicating-between-sync-and-async-code
 - [ ] Tower
 - [ ] add to Comparison to other languages
 - [ ] AWS
 - [ ] walkdir
-- [ ] <https://docs.rs/flagset/latest/flagset/>
+- [ ] [flagset][flagset] [flagset]: https://docs.rs/flagset/latest/flagset
 - [ ] notify
 - [ ] indicatif, ratatui
 - [ ] time
@@ -74,7 +84,7 @@
 - [ ] Macros
 - [ ] egui
 - [ ] Badges
-- [ ] rust and Docker - [ ] multistage builds
+- [ ] rust and Docker; multistage builds
 - [ ] rust + docker compose
 - [ ] rust + Mongo example
 - [ ] add a rust axum example
@@ -87,10 +97,10 @@
 - [ ] Languages
 - [ ] finish actor.md
 - [ ] Search within the book
-- [ ] <https://endler.dev/2019/tinysearch/>
-- [ ] <https://stork-search.net/>
-- [ ] <https://github.com/lucaong/minisearch>
-- [ ] <https://lucaongaro.eu/blog/2019/01/30/minisearch-client-side-fulltext-search-engine.html>
-- [ ] <https://github.com/typesense/typesense>
-- [ ] <https://news.ycombinator.com/item?id=23473303>
+- [ ] [tinysearch][tinysearch-website] [tinysearch-website]: https://endler.dev/2019/tinysearch
+- [ ] [stork-search.net][stork-search.net] [stork-search.net]: https://stork-search.net
+- [ ] [minisearch][minisearch] [minisearch]: https://github.com/lucaong/minisearch
+- [ ] [minisearch-client-side-fulltext-search-engine][minisearch-client-side-fulltext-search-engine] [minisearch-client-side-fulltext-search-engine]: https://lucaongaro.eu/blog/2019/01/30/minisearch-client-side-fulltext-search-engine.html
+- [ ] [typesense][typesense-github]  [typesense-github]: https://github.com/typesense/typesense
+- [ ] [A Tiny, Static, Full-Text Search Engine using Rust and WebAssembly][tinysearch] [tinysearch]: https://news.ycombinator.com/item?id=23473303
 - [ ] Algolia

drafts/architecture.md

@@ -1,3 +1,5 @@
 # Architecture + Rust
 
-- [Building a SaaS with Rust and Next.js | Rust & Web Dev with Josh Mo](https://joshmo.bearblog.dev/lets-build-a-saas-with-rust/)
+- [Building a SaaS with Rust and Next.js][building-a-saas-with-rust-and-next-js]⮳
+
+[building-a-saas-with-rust-and-next-js]: https://joshmo.bearblog.dev/lets-build-a-saas-with-rust/

drafts/asref.md

@@ -1,5 +1,8 @@
 <div class="hidden">
 TODO:
 
-[generics - When and why to use AsRef-T- instead of &T](https://stackoverflow.com/questions/66026309/when-and-why-to-use-asreft-instead-of-t)
+[When and why to use AsRef<T>instead of &T][stackoverflow-asref]⮳
+
+[stackoverflow-asref]: https://stackoverflow.com/questions/66026309/when-and-why-to-use-asreft-instead-of-t
+
 </div>

drafts/cd_ci.md

@@ -113,29 +113,44 @@ Example `.github/workflows/<name>.yml`
 
 [Optimizing CI/CD pipelines][blog-optimizing-ci-cd-pipelines]⮳
 
-<https://docs.github.com/en/actions/creating-actions/creating-a-docker-container-action>⮳
-<https://github.com/marketplace/actions/upload-a-build-artifact>⮳
+[Creating a docker container action][creating-a-docker-container-action-website]⮳
+
+[creating-a-docker-container-action-website]: https://docs.github.com/en/actions/creating-actions/creating-a-docker-container-action
+
+["Upload a Build Artifact" Github Action][upload-a-build-artifact-website]⮳
+
+[upload-a-build-artifact-website]: https://github.com/marketplace/actions/upload-a-build-artifact
 
 [`docker-cache`][docker-cache-github]{{hi:docker-cache}}⮳
 
 [Cached Docker images][cached-docker-images]⮳
 
 [Docker GitHub Action][docker-gitHub-action]⮳
 
-<https://docs.docker.com/build/cache/backends/>⮳
+[Cache storage backends][cache-storage-backends]⮳
+[cache-storage-backends]: https://docs.docker.com/build/cache/backends
 
-<https://docs.docker.com/build/ci/github-actions/cache/>⮳
+[Cache management with GitHub Actions][cache-management-with-gitHub-actions-website]⮳
+[cache-management-with-gitHub-actions-website]: https://docs.docker.com/build/ci/github-actions/cache/
 
-<https://stackoverflow.com/questions/61491484/how-to-cache-docker-compose-build-inside-github-action>⮳
+[How to cache docker-compose build inside github-action][stackoverflow-how-to-cache-docker-compose-build-inside-github-action]⮳
+[stackoverflow-how-to-cache-docker-compose-build-inside-github-action]: https://stackoverflow.com/questions/61491484/how-to-cache-docker-compose-build-inside-github-action
 
 {{#include ../refs/link-refs.md}}
+
 <div class="hidden">
 TODO:
 
-- [Optimizing CI/CD pipelines in your Rust projects](https://blog.logrocket.com/optimizing-ci-cd-pipelines-rust-projects/)
-- [install-action](https://github.com/taiki-e/install-action/) GitHub Action for installing development tools (mainly from GitHub Releases)
+- [Optimizing CI/CD pipelines in your Rust projects][blog-optimizing-ci-cd-pipelines-rust-project]⮳
+
+[blog-optimizing-ci-cd-pipelines-rust-project]: https://blog.logrocket.com/optimizing-ci-cd-pipelines-rust-projects/
+
+- [GitHub Action for installing development tools (mainly from GitHub Releases)][install-action]⮳
+
+[install-action]: https://github.com/taiki-e/install-action/
+
+[Experience about deploying mdbook on github using github action - tutorials - The Rust Programming Language Forum][deploying-mdbook-on-github-using-github-action]⮳
 
-Experience about deploying mdbook on github using github action - tutorials - The Rust Programming Language Forum
-<https://users.rust-lang.org/t/experience-about-deploying-mdbook-on-github-using-github-action/81408>
+[deploying-mdbook-on-github-using-github-action]: https://users.rust-lang.org/t/experience-about-deploying-mdbook-on-github-using-github-action/81408
 
 </div>

drafts/dependency_management.md

@@ -6,8 +6,12 @@ Keep your dependencies up-to-date
 
 Deps.rs uses semantic versioning to detect outdated or insecure dependencies in your project's`Cargo.toml`.
 
-- [deps.rs](https://deps.rs/)
+- [deps.rs][deps-rs-website]⮳
 
 ## Rust Digger
 
-We are collecting data about [Rust Crates](https://crates.io/) to find the common practices of Open Source Rust developers and trying to improve the Rust ecosystem. [rust-digger.code-maven.com](https://rust-digger.code-maven.com/)
+We are collecting data about [Rust Crates][crates.io]⮳ to find the common practices of Open Source Rust developers and trying to improve the Rust ecosystem. [rust-digger.code-maven.com][rust-digger]⮳
+
+[rust-digger]: https://rust-digger.code-maven.com/
+[crates.io]: https://crates.io/
+[deps-rs-website]: https://deps.rs

drafts/devops.md

@@ -2,6 +2,8 @@
 
 ## Daytona
 
-Daytona is a self-hosted and secure open source development environment manager. Daytona's support for Dev Containers standard enables developers to tailor their environments to exact specifications and share configurations for efficient collaboration.
+Daytona is a self-hosted and secure open source development environment manager. Daytona's support for Dev Containers standard enables developers to tailor their environments to exact specifications and share configurations for efficient collaboration
 
-- [daytona.io/dotfiles/diy-guide-to-transform-any-machine-into-a-codespace](https://www.daytona.io/dotfiles/diy-guide-to-transform-any-machine-into-a-codespace)
+[DIY Guide to Transform Any Machine into a Codespace][guide-to-transform-any-machine-into-a-codespace]⮳
+
+[guide-to-transform-any-machine-into-a-codespace]: https://www.daytona.io/dotfiles/diy-guide-to-transform-any-machine-into-a-codespace

drafts/reverse_proxy.md

@@ -2,20 +2,27 @@
 
 ## Rathole
 
-A lightweight and high-performance reverse proxy for NAT traversal, written in Rust. An alternative to frp and ngrok. [Rathole](https://github.com/rapiz1/rathole)
+A lightweight and high-performance reverse proxy for NAT traversal, written in Rust. An alternative to frp and ngrok. [Rathole][rathole-github]⮳
 
 ### ngrok
 
-- [ngrok secure ingress](https://github.com/ngrok/ngrok-rust)
-- [ngrok](https://ngrok.com/)
+- [ngrok secure ingress][ngrok-rust-github]⮳
+- [ngrok][ngrok-website]⮳
 
 ### nginx
 
-- [ngnix proxy manager](https://nginxproxymanager.com/)
+- [ngnix proxy manager][nginx-proxy-manager]⮳
 
 ## Pingora
 
 A library for building fast, reliable and evolvable network services.
 
-- [Pingora (github)](https://github.com/cloudflare/pingora/tree/main)
-- [Pingora quick start](https://github.com/cloudflare/pingora/blob/main/docs/quick_start.md)
+- [Pingora (github)][pingora-github]⮳
+- [Pingora quick start][pingora-quick-start-github]⮳
+
+[pingora-quick-start-github]: https://github.com/cloudflare/pingora/blob/main/docs/quick_start.md
+[rathole-github]: https://github.com/rapiz1/rathole
+[ngrok-rust-github]: https://github.com/ngrok/ngrok-rust
+[ngrok-website]: https://ngrok.com
+[nginx-proxy-manager]: https://nginxproxymanager.com/
+[pingora-github]: https://github.com/cloudflare/pingora/tree/main

src/about.md

@@ -2,11 +2,11 @@
 
 ## Table of contents
 
-- [Who this book is for](#who-this-book-is-for)
-- [How to read this book](#how-to-read-this-book)
-- [How to use the recipes](#how-to-use-the-recipes)
-- [A note about error handling](#a-note-about-error-handling)
-- [A note about crate representation](#a-note-about-crate-representation)
+- [Who this book is for][who-this-book-is-for]⮳
+- [How to read this book][how-to-read-this-book]⮳
+- [How to use the recipes][how-to-use-the-recipes]⮳
+- [A note about error handling][a-note-about-error-handling]⮳
+- [A note about crate representation][a-note-about-crate-representation]⮳
 
 ## Who this book is for
 
@@ -83,8 +83,15 @@ This cookbook is intended eventually to provide expansive coverage of the Rust c
 
 At present the cookbook is focused on the standard library, and on "core" or "foundational" crates - those crates that make up the most common programming tasks, and that the rest of the ecosystem builds off of.
 
+[a-note-about-crate-representation]: #a-note-about-crate-representation
+[a-note-about-error-handling]: #a-note-about-error-handling
+[how-to-use-the-recipes]: #how-to-use-the-recipes
+[how-to-read-this-book]: #how-to-read-this-book
+[who-this-book-is-for]: #who-this-book-is-for
 [index]: index.md
+
 {{#include refs/link-refs.md}}
+
 <div class="hidden">
 TODO: rewrite
 </div>

src/categories.md

@@ -89,9 +89,11 @@
 | [![cat-websocket][cat-websocket-badge]][cat-websocket] | [![actix_web][c-actix_web-badge]][c-actix_web] | |
 | [![cat-http-server][cat-http-server-badge]][cat-http-server] | | |
 
-[All Valid Categories]( https://crates.io/category_slugs )
+[All Valid Categories][crates.io-category_slugs]⮳
 
+[crates.io-category_slugs]: https://crates.io/category_slugs
 {{#include refs/link-refs.md}}
+
 <div class="hidden">
 TODO:
 </div>

src/categories/algorithms/sorting.md

@@ -39,6 +39,7 @@ TODO:
 
 ## Sorting + Rust
 
-- A Rust implementation of Glidesort, my stable adaptive quicksort/mergesort hybrid sorting algorithm. [glidesort](https://github.com/orlp/glidesort)
+- A Rust implementation of Glidesort,a stable adaptive quicksort/mergesort hybrid sorting algorithm: [glidesort][glidesort-github]⮳
 
+[glidesort-github]: https://github.com/orlp/glidesort
 </div>

src/categories/asynchronous/async_channels.incl.md

@@ -1,6 +1,7 @@
 | Recipe | Crates | Categories |
 |--------|--------|------------|
 |  |  | [![cat-asynchronous][cat-asynchronous-badge]][cat-asynchronous] |
+
 <div class="hidden">
 TODO:
 </div>

src/categories/asynchronous/async_traits.incl.md

@@ -1,6 +1,7 @@
 | Recipe | Crates | Categories |
 |--------|--------|------------|
 |  |  | [![cat-asynchronous][cat-asynchronous-badge]][cat-asynchronous] |
+
 <div class="hidden">
 TODO: add link to recipe
 </div>

src/categories/asynchronous/futures.incl.md

@@ -1,6 +1,7 @@
 | Recipe | Crates | Categories |
 |--------|--------|------------|
 |  |  | [![cat-asynchronous][cat-asynchronous-badge]][cat-asynchronous] |
+
 <div class="hidden">
 TODO:
 </div>