Fix markdown headings to get anchor links

Author: soareschen

blog/2024-12-19-early-preview-announcement.md

@@ -10,7 +10,7 @@ to introduce a new modular programming paradigm for Rust.
 
 <!-- truncate -->
 
-# A Quick Overview of Context-Generic Programming
+## A Quick Overview of Context-Generic Programming
 
 As its name implied, CGP makes it possible to write _context-generic_ programs that can work
 with any context type in Rust, i.e. the type that we typically refer to as `Self`.
@@ -42,7 +42,7 @@ If you are new here, you should check out the [CGP homepage](/) for a proper int
 Instead of rehearsing the full introduction, this blog post will cover some background about the
 project, the current status, and what to expect from here on.
 
-# How It All Started
+## How It All Started
 
 My name is [Soares Chen](https://maybevoid.com/soareschen), a.k.a. [MaybeVoid](https://maybevoid.com),
 and I am the creator of CGP. Even though this project is still new to the public, it has been ongoing
@@ -77,7 +77,7 @@ Compared to my previous attempts, I am hopeful that Rust serves as a sweetspot t
 programming language for modular design patterns, thanks to its advanced type systems as well as
 its rapidly expanding ecosystem.
 
-# Current Status
+## Current Status
 
 This blog post serves as an early preview announcement, and kickstarts many efforts that are
 still needed before we can be ready for a full release.
@@ -97,13 +97,13 @@ Depending on my time availability, it may take a year or more before I am ready
 of CGP. But in the meanwhile, I will start posting regular updates on my development process,
 which may be of interest for some of you reading this blog post.
 
-# Plans for 2025
+## Plans for 2025
 
 In the upcoming new year 2025, I have many plans laid out to prepare for an official release of
 CGP. This section is less about making promises, but more about making you aware of how much work
 is still needed before you should consider using CGP seriously.
 
-## Finish the CGP Book
+### Finish the CGP Book
 
 The most important goal I have for CGP is to finish writing my first book,
 [Context-Generic Programming Patterns](https://patterns.contextgeneric.dev).
@@ -112,7 +112,7 @@ My hope is that the book will help reduce the bus factor of CGP, so that even if
 unavailable to continue working on CGP, someone could still use the book as a basis
 to continue the work.
 
-## Improve Error Diagnostics
+### Improve Error Diagnostics
 
 A critical blocker that makes it challenging for me to teach about CGP is the poor error
 reporting returned from the Rust compiler, when there is any error arise from unsatisfied constraints.
@@ -137,7 +137,7 @@ The progress on improving the error messages is tracked on CGP's GitHub issue
 the forked compiler is documented in the
 [CGP book](https://patterns.contextgeneric.dev/debugging-techniques.html#improving-the-compiler-error-message).
 
-## Document the `cgp` Crate
+### Document the `cgp` Crate
 
 I have done quite a bit of writing about CGP on the project website and the book. But if you
 look at the Cargo documentation for the [`cgp` crate](https://docs.rs/cgp/), you would see
@@ -151,7 +151,7 @@ about relevant concepts.
 That said, I do plan to provide at least minimal documentation inside the `cgp` crate,
 to help onboarding programmers to projects that use the `cgp` crate.
 
-## Public Speaking
+### Public Speaking
 
 An effective way to spread the awareness of CGP is for me to speak about it at Rust conferences.
 I plan to apply to speak at major Rust conferences located in Europe, and hopefully I will get
@@ -163,7 +163,7 @@ by organizing online meetups. However, this would subject to my time availabilit
 from the community, as producing tech videos is not exactly my area of expertise.
 But in case if you are interested in such content, do let me know what you would like to see produced.
 
-## Improve the CGP Macros
+### Improve the CGP Macros
 
 The proc macros provided by the `cgp` crate were written in haste as quick proof of concepts
 to simplify the syntax for writing CGP programs. As a result, they are not that high in quality,
@@ -179,7 +179,7 @@ When I have the time, I plan to learn more about how to properly implement the p
 and implement them correctly with proper test coverage. This is important to provide good
 user experience, as developers will use the macros all the time when programming in CGP.
 
-## Developer Tooling
+### Developer Tooling
 
 For CGP to gain mainstream adoption, it is not sufficient to just make CGP powerful enough
 to solve difficult programming problems. In addition to that, we also need to make CGP
@@ -202,7 +202,7 @@ the cognitive burden of wiring CGP components can be automated by the IDE. But i
 much longer than one year for me to implement such features. In the meanwhile, I will probably
 explore on simpler options, such as building simple CLI tools for CGP.
 
-## Implement Advanced CGP features
+### Implement Advanced CGP features
 
 Aside from improving CGP macros, there are a few more advanced core constructs that I need to
 implement in the `cgp` crate to enable CGP to solve more use cases.
@@ -217,7 +217,7 @@ In case if you have interest in topics such as row polymorphism, datatype-generi
 and category theory, you might be interested to follow my progress on how I make use of these
 advanced concepts in CGP.
 
-## More Documentation
+### More Documentation
 
 It would be a big milestone if I am able to finish the first CGP book and document the `cgp`
 crate by the end of 2025. But I also hope to write more documentation in other forms, to
@@ -241,10 +241,10 @@ problem that you think CGP may help solving, I would love to hear more about it.
 This can help inform me what kind of topics is popular, and allows me to better
 prepared to produce content for those topics.
 
-# How You Can Help
+## How You Can Help
 
 If you have read till the end of this blog post, thank you for taking your time!
-If you are interested in CGP, the project homepage [lists many ways](/#contribution)
+If you are interested in CGP, the project homepage [lists many ways](/docs/contribute)
 you can help me continue my development on CGP.
 I look forward to see you again in the future updates for CGP!
 

blog/2025-01-09-v0.3.0-release.md

@@ -9,33 +9,33 @@ I'm excited to announce the release of [v0.3.0](https://github.com/contextgeneri
 
 <!-- truncate -->
 
-# New Book Chapters
+## New Book Chapters
 
 We’ve added a few new chapters to the [CGP Patterns](https://patterns.contextgeneric.dev/) book. Below is a brief summary of the newly published content.
 
-## Associated Types
+### Associated Types
 
 In the [launch announcement](/blog/early-preview-announcement/) for CGP, some readers remarked that CGP seemed to be primarily a dependency injection framework in Rust. While this observation captured part of its functionality, a key feature not yet covered was CGP's ability to use _abstract types_ in conjunction with the dependency injection of _types_.
 
 In the [new chapter](https://patterns.contextgeneric.dev/associated-types.html) of the book, we explore this powerful feature with a motivating example: implementing a context-generic authentication token validator that is not only generic over the `Context` but also over abstract `Time` and `AuthToken` types. The chapter also demonstrates how to use the `cgp_type!` macro to streamline the declaration of abstract type traits and how to employ `UseType` in component wiring to instantiate abstract types.
 
-## Error Handling
+### Error Handling
 
 CGP introduces a novel approach to error handling that differs significantly from the conventional patterns used in Rust today. In the [new chapter](https://patterns.contextgeneric.dev/error-handling.html) of the book, we begin by leveraging an abstract `Error` type from `HasErrorType` to define error-returning method signatures. The chapter then delves into how `CanRaiseError` and `CanWrapError` can be used to produce abstract errors within context-generic provider implementations. Further, the chapter discusses how to define context-generic error raisers and leverage the `UseDelegate` pattern for static dispatching of error handling to various providers.
 
-## Field Accessors
+### Field Accessors
 
 CGP provides a robust mechanism for dependency injection using [impl-side dependencies](https://patterns.contextgeneric.dev/impl-side-dependencies.html). However, since these dependencies are expressed through traits and constraints, we need to define _accessor traits_ to retrieve field values from a generic context.
 
 In the [new chapter](https://patterns.contextgeneric.dev/field-accessors.html), we explore different approaches for defining, using, and implementing accessor traits in CGP. This chapter explains how the `#[derive(HasField)]` macro operates and dives into the internal workings of `HasField` and `Symbol!`. It also introduces the` #[cgp_auto_getter]` and `#[cgp_getter]` macros, which automatically generate accessor provider implementations that work with `HasField`.
 
-# `cgp` v0.3.0 Release
+## `cgp` v0.3.0 Release
 
-The `cgp` crate has been upgraded from `v0.2.0` to `v0.3.0`, introducing new features that significantly enhance usability and include minor breaking changes. You can view the full [release notes here](https://github.com/contextgeneric/cgp/releases/tag/v0.3.0). Additionally, the [Hello World example](/#hello-world-example) on the project homepage has been updated to showcase a simplified implementation using the latest CGP constructs.
+The `cgp` crate has been upgraded from `v0.2.0` to `v0.3.0`, introducing new features that significantly enhance usability and include minor breaking changes. You can view the full [release notes here](https://github.com/contextgeneric/cgp/releases/tag/v0.3.0). Additionally, the [Hello World example](/docs/tutorials/hello) on the project homepage has been updated to showcase a simplified implementation using the latest CGP constructs.
 
 Below is a summary of key updates in this release.
 
-## `cgp_type!` Macro
+### `cgp_type!` Macro
 
 The new `cgp_type!` macro streamlines the process of declaring abstract type traits, enabling you to define them in a single line of code. For instance, the `HasErrorType` trait in `cgp` is now defined as:
 
@@ -64,7 +64,7 @@ where
 
 For a detailed explanation of cgp_type! and its usage, check out the new [Associated Types](https://patterns.contextgeneric.dev/associated-types.html#defining-abstract-type-traits-with-cgp_type) chapter in the CGP Patterns book.
 
-## `#[cgp_auto_getter]` Macro
+### `#[cgp_auto_getter]` Macro
 
 The `#[cgp_auto_getter]` macro simplifies the process of defining accessor traits with blanket implementations based on `HasField`. When a trait is marked with `#[cgp_auto_getter]`, any context deriving `HasField` that has the required fields and types will automatically implement the specified trait without additional boilerplate.
 
@@ -96,7 +96,7 @@ In this example, the `Person` struct derives the `HasField` trait, which automat
 
 For more details on `#[cgp_auto_getter]`, refer to the [Generic Accessor Providers](https://patterns.contextgeneric.dev/generic-accessor-providers.html#the-cgp_auto_getter-macro) chapter in the CGP Patterns book.
 
-## `#[cgp_getter]` Macro
+### `#[cgp_getter]` Macro
 
 The `#[cgp_getter]` macro, like `#[cgp_auto_getter]`, generates blanket implementations that make use of `HasField`. However, `#[cgp_getter]` extends functionality by also creating full CGP constructs for the trait, similar to `#[cgp_component]`. This requires explicit wiring in the context using `delegate_components!`. Additionally, `#[cgp_getter]` derives a blanket implementation for the `UseFields` provider, so that it can be used inside the component wiring as follows:
 
@@ -138,7 +138,7 @@ fn main() {
 
 For additional information on `#[cgp_getter]`, refer to the [Generic Accessor Providers](https://patterns.contextgeneric.dev/generic-accessor-providers.html#the-cgp_getter-macro) chapter of the CGP Patterns book.
 
-## `CanWrapError` Trait
+### `CanWrapError` Trait
 
 The `CanWrapError` trait has been introduced to streamline the process of wrapping existing errors. Its definition is as follows:
 
@@ -155,13 +155,13 @@ Previously, error wrapping relied on using `CanRaiseError` with a tuple, such as
 
 For more details about the usage of `CanWrapError`, refer to the [Error Wrapping](https://patterns.contextgeneric.dev/error-wrapping.html) chapter in the CGP Patterns book.
 
-## `cgp-error-anyhow` Crate
+### `cgp-error-anyhow` Crate
 
 We have published a new [`cgp-error-anyhow`](https://docs.rs/cgp-error-anyhow/0.3.0/cgp_error_anyhow/index.html) crate, which provides context-generic error raisers for `anyhow::Error`. This addition complements the previously published [`cgp-error-eyre`](https://docs.rs/cgp-error-eyre/0.3.0/cgp_error_eyre/index.html) and [`cgp-error-std`](https://docs.rs/cgp-error-std/0.3.0/cgp_error_std/index.html) crates, which support CGP error handling with `eyre::Error` and `Box<dyn core::error::Error + Send + Sync + 'static>`. Given the popularity of `anyhow::Error`, this crate extends support for its usage.
 
 Details on using `cgp-error-anyhow` for error handling can be found in the [Error Handling](https://patterns.contextgeneric.dev/error-handling.html#the-cgp-error-anyhow-crate) chapter of the CGP Patterns book.
 
-## `cgp-runtime` Crate
+### `cgp-runtime` Crate
 
 The new [`cgp-runtime`](https://docs.rs/cgp-runtime/0.3.0/cgp_runtime/index.html) crate introduces standardized interfaces for runtimes, paving the way for future discussions on asynchronous programming in the CGP Patterns book.
 
@@ -180,23 +180,23 @@ pub trait HasRuntime: HasRuntimeType {
 
 Stay tuned for updates to the CGP Patterns book for more information on using pluggable async runtimes with CGP.
 
-# Future Work
+## Future Work
 
 There are several additional features and improvements I had hoped to include in this update. However, with my New Year vacation coming to an end, I need to wrap up the current progress. Below are some of the tasks deferred to future updates.
 
-## Documenting the `cgp` Crate
+### Documenting the `cgp` Crate
 
 While the CGP Patterns book offers extensive conceptual coverage, the `cgp` crate currently lacks comprehensive Rustdoc documentation. Many constructs remain undocumented, and users must rely on the CGP Patterns book or this website for detailed guidance.
 
 In future updates, I plan to add concise Rustdoc comments to these constructs and include links to relevant chapters in the CGP Patterns book. This will help bridge the gap and provide in-crate documentation to enhance usability. For now, all detailed information about CGP is accessible only through the book and website.
 
-## Tutorials with More Complex Use Cases
+### Tutorials with More Complex Use Cases
 
 During the [launch announcement](/blog/early-preview-announcement/), many readers noted the lack of practical examples demonstrating how CGP can address more complex, real-world problems. While I had planned to create such tutorials, much of my time was spent completing relevant chapters and updating the `cgp` crate. I ask for your patience as I work on delivering concise, compelling examples to better illustrate CGP's utility.
 
 In the meantime, the simplified examples in the recently added [Associated Types](https://patterns.contextgeneric.dev/associated-types.html), [Error Handling](https://patterns.contextgeneric.dev/error-handling.html), and [Field Accessors](https://patterns.contextgeneric.dev/field-accessors.html) chapters provide a glimpse into CGP's practical applications. These include examples like validating whether an authentication token has expired and making HTTP API calls to fetch messages. While not exhaustive, these examples go beyond the basic "Hello World" tutorial on the homepage and offer a clearer picture of how CGP can be applied to your projects.
 
-# Acknowledgement
+## Acknowledgement
 
 A big thank you to [@marvin-hansen](https://github.com/marvin-hansen) for his enthusiastic involvement in discussions, testing CGP with real-world projects, and providing invaluable feedback! The implementation of the `#[cgp_getter]` and `#[cgp_auto_getter]` macros was primarily motivated by his input, highlighting that the direct use of `HasField` could be too complex for beginners. Thanks to his suggestions, CGP now offers a more seamless and intuitive experience for declaring and using field accessor traits.