Markdown linting: Headings / Headers (#5343)

* MD002 -- first heading should be a top-level heading

* fix multiple H1s

* heading increments

* fix lots of headings

* fix headings

* fix headings

* fix headings

* fix headings

* fix headings

* fix md019 multiple spaces

* oops, missed spacing

* oops, missed spaces

docs/api/index.md

@@ -1 +1 @@
-## Akka.NET API Documentation
+# Akka.NET API Documentation

docs/articles/actors/di-core.md

@@ -10,14 +10,14 @@ title: DI Core
 
 **Actor Producer Extension** library is used to create a Dependency Injection Container for the [Akka.NET](https://github.com/akkadotnet/akka.net) framework.
 
-# What is it?
+## What is it?
 
 **Akka.DI.Core** is an **ActorSystem extension** library for the Akka.NET
 framework that provides a simple way to create an Actor Dependency Resolver
 that can be used an alternative to the basic capabilities of [Props](xref:receive-actor-api#props)
 when you have actors with multiple dependencies.
 
-# How do you create an Extension?
+## How do you create an Extension?
 
 * Create a new class library
 * Reference your favorite IoC Container, the Akka.DI.Core, and of course Akka

docs/articles/actors/dispatchers.md

@@ -11,7 +11,7 @@ Dispatchers are responsible for scheduling all code that run inside the `ActorSy
 
 By default, all actors share a single **Global Dispatcher**. Unless you change the configuration, this dispatcher uses the *.NET Thread Pool* behind the scenes, which is optimized for most common scenarios. **That means the default configuration should be *good enough* for most cases.**
 
-#### Why should I use different dispatchers?
+### Why should I use different dispatchers?
 
 When messages arrive in the [actor's mailbox](xref:mailboxes), the dispatcher schedules the delivery of messages in batches, and tries to deliver the entire batch before releasing the thread to another actor. While the default configuration is *good enough* for most scenarios, you may want to change ([through configuration](#configuring-dispatchers)) how much time the scheduler should spend running each actor.
 
@@ -66,7 +66,7 @@ Or you can also set it up in code:
 system.ActorOf(Props.Create<MyActor>().WithDispatcher("my-dispatcher"), "my-actor");
 ```
 
-#### Built-in Dispatcher Configurations
+### Built-in Dispatcher Configurations
 
 Some dispatcher configurations are available out-of-the-box for convenience. You can use them during actor deployment, [as described above](#configuring-dispatchers).
 

docs/articles/actors/routers.md

@@ -19,7 +19,7 @@ Akka.NET comes with several useful routers you can choose right out of the box,
 
 Routers can be deployed in multiple ways, using code or configuration.
 
-#### Code deployment
+### Code deployment
 
 The example below shows how to deploy 5 workers using a round robin router:
 
@@ -35,7 +35,7 @@ The above code can also be written as:
 var props = new RoundRobinPool(5).Props(Props.Create<Worker>());
 ```
 
-#### Configuration deployment
+### Configuration deployment
 
 The same router may be defined using a [HOCON deployment configuration](xref:configuration).
 
@@ -88,7 +88,7 @@ There are two types of routers:
 > [!NOTE]
 > Most routing strategies listed below are available in both types. Some of them may be available only in one type due to implementation requirements.
 
-#### Supervision
+### Supervision
 
 Routers are implemented as actors, so a router is supervised by it's parent, and they may supervise children.
 

docs/articles/clustering/cluster-overview.md

@@ -88,7 +88,7 @@ Once you've installed Akka.Cluster, we need to update our HOCON configuration to
 > [!NOTE]
 > Akka.Cluster depends on Akka.Remote.
 
-#### Seed Node Configuration
+### Seed Node Configuration
 
 ```xml
 akka {

docs/articles/concepts/configuration.md

@@ -39,21 +39,21 @@ From there, we can create our `ActorSystem`:
 
 Akka.NET leverages a configuration format, called HOCON, to allow you to configure your Akka.NET applications with whatever level of granularity you want.
 
-#### What is HOCON?
+### What is HOCON?
 
 HOCON (Human-Optimized Config Object Notation) is a flexible and extensible configuration format.
 It allows you to configure everything from Akka.NET's `IActorRefProvider` implementation: logging, network transports, and (more commonly) how individual actors are deployed.
 
 Values returned by HOCON are strongly typed, which means you can fetch out an `int`, a `Timespan`, etc.
 
-#### What can I do with HOCON?
+### What can I do with HOCON?
 
 HOCON allows you to embed easy-to-read configuration inside of the otherwise hard-to-read XML in App.config and Web.config.
 HOCON also lets you query configs by their section paths, and those sections are exposed strongly typed and parsed values you can use inside your applications.
 
 HOCON also lets you nest and/or chain sections of configuration, creating layers of granularity and providing you a semantically namespaced config.
 
-#### What is HOCON usually used for?
+### What is HOCON usually used for?
 
 HOCON is commonly used for tuning logging settings, enabling special modules (such as `Akka.Remote`), or configuring deployments such as the `Dispatcher` or `Router` used for a particular actor.
 
@@ -73,7 +73,7 @@ var system = ActorSystem.Create("MyActorSystem", config);
 
 As you can see in that example, a HOCON `Config` object can be parsed from a `string` using the `ConfigurationFactory.ParseString` method. Once you have a `Config` object, you can then pass this to your `ActorSystem` inside the `ActorSystem.Create` method.
 
-#### "Deployment"? What's that?
+### "Deployment"? What's that?
 
 Deployment is a vague concept, but it's closely tied to HOCON. An actor is "deployed" when it is instantiated and put into service within the `ActorSystem` somewhere.
 

docs/articles/concepts/terminology.md

@@ -11,11 +11,11 @@ In this chapter we attempt to establish a common terminology to define a solid g
 
 Concurrency and parallelism are related concepts, but there are small differences. Concurrency means that two or more tasks are making progress even though they might not be executing simultaneously. For example, this can be realized with time slicing where parts of tasks are executed sequentially and mixed with parts of other tasks. By contrast, Parallelism arises when the execution can be truly simultaneous.
 
-#### Concurrency
+### Concurrency
 
 ![Concurrency](/images/concurrency.png)
 
-#### Parallelism
+### Parallelism
 
 ![Parallelism](/images/parallelism.png)
 

docs/articles/configuration/akka.cluster.md

@@ -3,7 +3,7 @@ uid: akka-cluster-configuration
 title: Akka.Cluster Configuration
 ---
 
-## Akka.Cluster Configuration
+# Akka.Cluster Configuration
 
 Below is the default HOCON configuration for the base `Akka.Cluster` package.
 

docs/articles/configuration/akka.md

@@ -3,7 +3,7 @@ uid: akka-configuration
 title: Akka Configuration
 ---
 
-## Akka Configuration
+# Akka Configuration
 
 Below is the default HOCON configuration for the base `Akka` package.
 

docs/articles/configuration/akka.persistence.md

@@ -3,7 +3,7 @@ uid: akka-persistence-configuration
 title: Akka.Persistence Configuration
 ---
 
-## Akka.Persistence Configuration
+# Akka.Persistence Configuration
 
 Below is the default HOCON configuration for the base `Akka.Persistence` package.
 

docs/articles/configuration/akka.remote.md

@@ -3,7 +3,7 @@ uid: akka-remote-configuration
 title: Akka.Remote Configuration
 ---
 
-## Akka.Remote Configuration
+# Akka.Remote Configuration
 
 Below is the default HOCON configuration for the base `Akka.Remote` package.
 

docs/articles/configuration/akka.streams.md

@@ -3,7 +3,7 @@ uid: akka-streams-configuration
 title: Akka.Streams Configuration
 ---
 
-## Akka.Streams Configuration
+# Akka.Streams Configuration
 
 Below is the default HOCON configuration for the base `Akka.Streams` package.
 

docs/articles/configuration/akka.testkit.md

@@ -1,4 +1,4 @@
-## Akka.TestKit Configuration
+# Akka.TestKit Configuration
 
 Below is the default HOCON configuration for the base `Akka.TestKit` package.
 

docs/articles/intro/akka-users.md

@@ -10,55 +10,55 @@ Any system that has the need for high-throughput and low latency is a good candi
 
 ## Akka.NET Users
 
-#### Transaction processing (Online Gaming, Finance/Banking, Trading, Statistics, Betting, Social Media, Telecom)
+### Transaction processing (Online Gaming, Finance/Banking, Trading, Statistics, Betting, Social Media, Telecom)
 
 * [CellularSales](https://youtu.be/G3ZafPNI-hk?t=31m6s)
 
-#### Service backend (any industry, any app)
+### Service backend (any industry, any app)
 
 [IVC Business Systems](http://ivcbusinesssystems.com/):
 
 > Sam Covington, IVC Business Systems: We had an in-house "Actor" system that we replaced with Akka.Net, which allowed us to innovate and be productive elsewhere, and not reinvent the wheel(not to mention test it to death). This back end of Microservices forms the basis of all of our products and services. We're using it in our Enterprise Social Product, and our new Livescan Office product for Livescan fingerprinting customers.
 
-#### Concurrency/parallelism (any app)
+### Concurrency/parallelism (any app)
 
 Share of an article by Joel Mueller, Software Architect, SNL Financial
 
 * [SNL Financial (a subsidiary of McGraw Hill): Akka.NET Goes to Wall Street](https://petabridge.com/blog/akkadotnet-goes-to-wall-street/)
 
-#### Simulation
+### Simulation
 
 Master/Worker, Compute Grid, MapReduce etc.
 
-#### Batch processing (any industry)
+### Batch processing (any industry)
 
 Camel integration to hook up with batch data sources Actors divide and conquer the batch workloads
 
-#### Communications Hub (Telecom, Web media, Mobile media)
+### Communications Hub (Telecom, Web media, Mobile media)
 
 * [EventDay: real-time conference and event management at scale with Akka.NET](https://youtu.be/G3ZafPNI-hk?t=6m16s)
 
-#### Gaming and Betting (MOM, online gaming, betting)
+### Gaming and Betting (MOM, online gaming, betting)
 
 Scale up, scale out, fault-tolerance / HA
 
-#### Business Intelligence/Data Mining/general purpose crunching
+### Business Intelligence/Data Mining/general purpose crunching
 
 Tweet from Philip Laureano with links.
 
 * [Real-time Clickstream Processing at Domain.au with Octopus Deploy and Akka.NET](https://twitter.com/philiplaureano/status/735976018993778688)
 
-#### Internet of Things
+### Internet of Things
 
 * [Synchromatics: Real-time public transit tracking and analytics using Akka.NET](https://youtu.be/YuY1ziEqifU?t=3m38s)
 
-#### Complex Event Stream Processing
+### Complex Event Stream Processing
 
 Archive of a blog post by Aaron Stannard from July 2014.
 
 * [MarkedUp Analytics: Real-time Marketing Automation with Distributed Actor Systems and Akka.NET](http://www.aaronstannard.com/markedup-akkadotnet/)
 
-#### Blockchain
+### Blockchain
 
 "NEO is a non-profit community-driven blockchain project. It utilizes blockchain technology and digital identity to digitize assets and automate the management of digital assets using smart contracts." (source: neo.org)
 

docs/articles/intro/modules.md

@@ -8,7 +8,7 @@ Before we delve further into writing our first actors, we should stop for a mome
 that come out-of-the-box. This will help you identify which modules and libraries provide the functionality you
 want to use in your system.
 
-### Actors (`Akka` Library, the Core)
+## Actors (`Akka` Library, the Core)
 
 The use of actors across Akka.NET libraries provides a consistent, integrated model that relieves you from individually
 solving the challenges that arise in concurrent or distributed system design. From a birds-eye view,
@@ -27,7 +27,7 @@ Challenges that actors solve include:
 * How to handle errors in a multi-threaded environment.
 * How to protect my project from the pitfalls of concurrency.
 
-### Remoting
+## Remoting
 
 Remoting enables actors that are remote, living on different computers, to seamlessly exchange messages.
 Remoting can be enabled mostly with configuration; it has only a few APIs. Thanks to the actor model,
@@ -44,7 +44,7 @@ Some of the challenges Remoting solves are:
   all transparently.
 * How to multiplex communications from an unrelated set of actors on the same network connection, all transparently.
 
-### Cluster
+## Cluster
 
 If you have a set of actor systems that cooperate to solve some business problem, then you likely want to manage these set of
 systems in a disciplined way. While Remoting solves the problem of addressing and communicating with components of
@@ -61,7 +61,7 @@ The challenges the Cluster module solves, among others, are:
 * How to distribute computations among the current set of members.
 * How to designate members of the cluster to a certain role; in other words, to provide certain services and not others.
 
-### Cluster Sharding
+## Cluster Sharding
 
 Sharding helps to solve the problem of distributing a set of actors among members of an Akka.NET cluster.
 Sharding is a pattern that is mostly used together with Persistence to balance a large set of persistent entities
@@ -74,7 +74,7 @@ The challenge space that Sharding targets:
 * How to migrate entities from a crashed system without losing their state.
 * How to ensure that an entity does not exist on multiple systems at the same time and is hence kept consistent.
 
-### Cluster Singleton
+## Cluster Singleton
 
 A common (in fact, a bit too common) use case in distributed systems is to have a single entity responsible
 for a given task which is shared among other members of the cluster and migrated if the host system fails.
@@ -89,7 +89,7 @@ The Singleton module can be used to solve these challenges:
 * How to ensure that the service is up even if the system hosting it currently crashes or shut down during the process of scaling down.
 * How to reach this instance from any member of the cluster assuming that it can migrate to other systems over time.
 
-### Cluster Publish-Subscribe
+## Cluster Publish-Subscribe
 
 For coordination among systems, it is often necessary to distribute messages to all, or one system of a set of
 interested systems in a cluster. This pattern is usually called publish-subscribe and this module solves this exact
@@ -101,7 +101,7 @@ Cluster Publish-Subscribe is intended to solve the following challenges:
 * How to send a message to a member from an interested set of parties in a cluster.
 * How to subscribe and unsubscribe for events of a certain topic in the cluster.
 
-### Persistence
+## Persistence
 
 Just like objects in OOP, actors keep their state in volatile memory. Once the system is shut down, gracefully or
 because of a crash, all data that was in memory is lost. Persistence provides patterns to enable actors to persist
@@ -117,7 +117,7 @@ Persistence tackles the following challenges:
 * How to introspect domain events that have lead an entity to its current state.
 * How to leverage [Event Sourcing](https://martinfowler.com/eaaDev/EventSourcing.html) in my application to support long-running processes while the project continues to evolve.
 
-### Distributed Data
+## Distributed Data
 
 In situations where eventual consistency is acceptable, it is possible to share data between nodes in
 an Akka.NET Cluster and accept both reads and writes even in the face of cluster partitions. This can be
@@ -130,7 +130,7 @@ Distributed Data is intended to solve the following challenges:
 * How to accept writes even in the face of cluster partitions.
 * How to share data while at the same time ensuring low-latency local read and write access.
 
-### Streams
+## Streams
 
 Actors are a fundamental model for concurrency, but there are common patterns where their use requires the user
 to implement the same pattern over and over. Very common is the scenario where a chain, or graph, of actors, need to

docs/articles/intro/use-case-and-deployment-scenarios.md

@@ -96,7 +96,7 @@ to build your Windows Services. It radically simplifies hosting Windows Services
 
 The quickest way to get started with TopShelf is by creating a Console Application. Which would look like this:
 
-#### Program.cs
+### Program.cs
 
 ```csharp
 using Akka.Actor;
@@ -161,7 +161,7 @@ The Azure PaaS Worker Role implementation is very similar to the [Windows Servic
 The quickest way to get started with Akka.Net is to create a simple Worker Role which invokes the top-level
 user-actor in the RunAsync() method, as follows:
 
-#### WorkerRole.cs
+### WorkerRole.cs
 
 ```csharp
 using Akka.Actor;

docs/articles/intro/what-problems-does-actor-model-solve.md

@@ -9,7 +9,7 @@ unique challenges of highly distributed systems. To fully understand why the act
 identify mismatches between traditional approaches to programming and the realities of concurrent and distributed
 computing.
 
-### The illusion of encapsulation
+## The illusion of encapsulation
 
 Object-oriented programming (OOP) is a widely-accepted, familiar programming model. One of its core pillars is
 _encapsulation_. Encapsulation dictates that the internal data of an object is not accessible directly from the outside;
@@ -83,7 +83,7 @@ As a result, threads are what really drive execution:
    are inefficient and easily lead to deadlocks in any application of real-world scale.**
 * **Locks work locally, attempts to make them distributed exist, but offer limited potential for scaling out.**
 
-### The illusion of shared memory on modern computer architectures
+## The illusion of shared memory on modern computer architectures
 
 Programming models of the 80'-90's conceptualize that writing to a variable means writing to a memory location directly
 (which somewhat muddies the water that local variables might exist only in registers). On modern architectures -
@@ -107,7 +107,7 @@ or which atomic structures to use is a dark art.
 * **There is no real shared memory anymore, CPU cores pass chunks of data (cache lines) explicitly to each other just as computers on a network do. Inter-CPU communication and network communication have more in common than many realize. Passing messages is the norm now be it across CPUs or networked computers.**
 * **Instead of hiding the message passing aspect through variables marked as shared or using atomic data structures, a more disciplined and principled approach is to keep state local to a concurrent entity and propagate data or events between concurrent entities explicitly via messages.**
 
-### The illusion of a call stack
+## The illusion of a call stack
 
 Today, we often take call stacks for granted. But, they were invented in an era where concurrent programming
 was not as important because multi-CPU systems were not common. Call stacks do not cross threads and hence,
@@ -154,7 +154,7 @@ involved (where message losses are to be expected).**
    (a long queue), delays caused by garbage collection, etc. In face of these, concurrent systems should handle response
    deadlines in the form of timeouts, just like networked/distributed systems.**  
 
-### How the actor model meets the needs of concurrent, distributed systems
+## How the actor model meets the needs of concurrent, distributed systems
 
 As described in the sections above, common programming practices cannot properly address the needs of modern concurrent
 and distributed systems.
@@ -170,7 +170,7 @@ In particular, we would like to:
 
 The actor model accomplishes all of these goals. The following topics describe how.
 
-### Usage of message passing avoids locking and blocking
+## Usage of message passing avoids locking and blocking
 
 Instead of calling methods, actors send messages to each other. Sending a message does not transfer the thread
 of execution from the sender to the destination. An actor can send a message and continue without blocking.
@@ -230,7 +230,7 @@ This is a very simple model and it solves the issues enumerated previously:
 * State of actors is local and not shared, changes and data is propagated via messages, which maps to how modern
    memory hierarchy actually works.    In many cases, this means transferring over only the cache lines that contain the data in the message while keeping local state and data cached at the original core. The same model maps exactly to remote communication where the state is kept in the RAM of machines and changes/data is propagated over the network as packets.
 
-### Actors handle error situations gracefully
+## Actors handle error situations gracefully
 
 Since we have no longer a shared call stack between actors that send messages to each other, we need to handle
 error situations differently. There are two kinds of errors we need to consider: