Lint and format markdown files (#422)

.github/workflows/lint.yml

@@ -0,0 +1,16 @@
+name: 'Lint Markdown Files'
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  spellcheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: articulate/actions-markdownlint@v1
+        with:
+          config: .markdownlint.json
+          files: 'content/**/*.md'
+          ignore: node_modules

.markdownlint.json

@@ -1,5 +1,12 @@
 {
-  "MD013": { "line_length": 120, "tables": false, "code_blocks": false },
+  "MD001": false,
+  "MD013": {
+    "line_length": 120,
+    "tables": false,
+    "code_blocks": false
+  },
+  "MD024": false,
   "MD034": false,
-  "MD040": false
+  "MD040": false,
+  "MD055": false
 }

content/icerpc-for-ice-users/high-level-comparison/ice-reinvented.md

@@ -14,6 +14,7 @@ Ice is a one-stop solution for building network applications. With Ice, you get
 components to help you build portable, multi-language networked applications.
 
 Ice includes:
+
 - an RPC framework
 - IDL and serialization format (Slice)
 - configuration (Ice properties)
@@ -26,6 +27,7 @@ Ice includes:
 On the other hand, IceRPC has a single focus: RPCs (the name gave it away!). When building an application with IceRPC,
 you use IceRPC for your RPCs, and you need to look outside IceRPC for other functionalities. For example, you could
 select:
+
 - IceRPC for your RPCs
 - Slice or Protobuf to define your network APIs
 - YAML for configuration

content/icerpc-for-ice-users/high-level-comparison/using-icerpc-with-ice.md

@@ -13,6 +13,7 @@ using IceRPC, or use IceRPC to create new services for your Ice clients.
 
 If you start from an existing Ice client or server, the first step is to convert your Slice definitions (in `.ice`
 files) to the new Slice syntax. The converted Slice files must specify `Slice1` mode:
+
 ```slice
 mode = Slice1 // required for interop with Ice
 ...

content/icerpc-for-ice-users/slice/converting-ice-into-slice.md

@@ -273,7 +273,7 @@ class Person {
 With the .ice syntax, the return type of an operation can be split between a return type and out parameters, whereas
 with the .slice syntax, an operation has only "in" parameters but can return a tuple.
 
-When converting .ice definitions into .slice definitions, keep in mind that Ice encodes out parameters _before_ the
+When converting .ice definitions into .slice definitions, keep in mind that Ice encodes out parameters *before* the
 return type.
 
 {% aside alignment="top" %}

content/icerpc-for-ice-users/slice/ice-object.md

@@ -79,7 +79,7 @@ unnecessary (`uncheckedCast` works just as well), it's shown by all Ice demos an
 The net result is: if you reimplement an existing Ice server with IceRPC, your services need to implement `Ice::Object`
 when they are being "checked cast" by existing Ice client applications.
 
-## Checked cast and unchecked cast in IceRPC for C#
+## Checked cast and unchecked cast in IceRPC for C\#
 
 If you like `checkedCast` and want to keep check-casting your proxies, the IceRPC + Slice integration provides an
 equivalent API: [AsAsync]. The target service must implement `Ice::Object`; otherwise, `AsAsync` will fail with a

content/icerpc-for-ice-users/slice/new-slice.md

@@ -16,6 +16,7 @@ applications.
 
 With Ice, the version of the Ice encoding to use when sending a request is a runtime decision. You can reconfigure a
 proxy to use the version of your choice. For example:
+
 ```csharp {% title="Setting the Ice encoding version with Ice for C#" %}
 helloPrx = helloPrx.ice_encodingVersion(Ice.Util.Encoding_1_0);
 ```
@@ -27,12 +28,14 @@ With the new Slice language, the encoding to use is decided at build-time, when
 define an interface, the encoding for operation arguments and return values is specified unambiguously with the
 [mode statement](/slice1/language-guide/compilation-mode), and gets hard-coded in the generated code.
 
-#### Example
+### Example
 
 ```slice
 mode = Slice1
 ```
+
 or
+
 ```slice
 mode = Slice2
 ```
@@ -46,19 +49,20 @@ A Slice file that doesn't specify a compilation mode uses the default mode: Slic
 
 The compilation mode also determines which definitions are allowed in your Slice file.
 
-#### Slice1
+### Slice1
 
 This mode provides an equivalent syntax for all Slice definitions in the .ice syntax, including classes, exceptions,
 interfaces, and structs. The names are mostly the same: for example, a class in a `.ice` file corresponds to a
 class in a `.slice` file, and a struct in a `.ice` file corresponds to a compact struct in a `.slice` file.
 
 You should use this mode when (and only when) you need to send or receive requests to and from Ice applications.
 
-#### Slice2
+### Slice2
 
 This is the default mode and the preferred mode when you don't need interop with Ice applications.
 
 This mode allows you to mark any type as optional with the `?` suffix. For example:
+
 ```slice
 // Implicitly uses `mode = Slice2`
 
@@ -69,25 +73,28 @@ interface Translator {
 ```
 
 Slice2 also provides:
- - stream parameters
- - unsigned integer types such as uint32
- - variable-size integer types such as varint64
- - underlying types for enums
- - structs that can be augmented while maintaining on-the-wire compatibility
 
-However, Slice2 is not a superset of Slice1. The following constructs are only accepted in Slice1 mode:
- - classes, including AnyClass
- - exceptions
+- stream parameters
+- unsigned integer types such as uint32
+- variable-size integer types such as varint64
+- underlying types for enums
+- structs that can be augmented while maintaining on-the-wire compatibility
+
+However, Slice2 is not a superset of Slice1. The following constructs are only accepted in Slice1 mode
+
+- classes, including AnyClass
+- exceptions
 
 ## New constructs
 
 The .slice syntax adds a few constructs that are available with both Slice1 and Slice2 but have no equivalent with the
 .ice syntax, namely:
- - anonymous sequences and dictionaries\
-   You can now use `Sequence<string>` directly as a parameter or field type.
- - custom types\
-   A custom type is a type that you encode and decode yourself in all language mappings.
- - typealias\
-   A typealias is a new name for another type.
+
+- anonymous sequences and dictionaries\
+  You can now use `Sequence<string>` directly as a parameter or field type.
+- custom types\
+  A custom type is a type that you encode and decode yourself in all language mappings.
+- typealias\
+  A typealias is a new name for another type.
 
 [convert]:  converting-ice-into-slice

content/icerpc/dependency-injection/dispatch-pipeline-with-di.md

@@ -112,9 +112,9 @@ leaf dispatcher via services injected by a DI container.
 
 Such a DI-friendly middleware needs to implement one of the following `IMiddleware` interfaces:
 
-- [IMiddleware<TDep>](csharp:IceRpc.Extensions.DependencyInjection.IMiddleware-1)
-- [IMiddleware<TDep1, TDep2>](csharp:IceRpc.Extensions.DependencyInjection.IMiddleware-2)
-- [IMiddleware<TDep1, TDep2, TDep3>](csharp:IceRpc.Extensions.DependencyInjection.IMiddleware-3)
+- [`IMiddleware<TDep>`](csharp:IceRpc.Extensions.DependencyInjection.IMiddleware-1)
+- [`IMiddleware<TDep1, TDep2>`](csharp:IceRpc.Extensions.DependencyInjection.IMiddleware-2)
+- [`IMiddleware<TDep1, TDep2, TDep3>`](csharp:IceRpc.Extensions.DependencyInjection.IMiddleware-3)
 
 For example, say we want to reimplement the deadline middleware in a more DI-friendly fashion. The standard deadline
 middleware reads the deadline field and creates a deadline feature to communicate this deadline to downstream middleware

content/icerpc/duplex-transport.md

@@ -41,10 +41,10 @@ See also [Security with TLS][security-with-tls] for additional information.
 
 The C# duplex transport abstraction is composed of a number of interfaces that a custom transport needs to implement:
 
-- [IDuplexClientTransport]: a factory to create outgoing connections
-- [IDuplexServerTransport]: a factory to create listeners
-- [IListener<IDuplexConnection>]: a factory to listen for and create incoming connections
-- [IDuplexConnection]: a connection to allow a client and server to communicate
+- [`IDuplexClientTransport`]: a factory to create outgoing connections
+- [`IDuplexServerTransport`]: a factory to create listeners
+- [`IListener<IDuplexConnection>`]: a factory to listen for and create incoming connections
+- [`IDuplexConnection`]: a connection to allow a client and server to communicate
 
 The API documentation of these interfaces specifies the contract a custom transport needs to comply with.
 
@@ -60,10 +60,10 @@ To use a custom transport, the application needs to provide an instance of `IDup
 [flow-control]: https://en.wikipedia.org/wiki/Flow_control_(data)
 [ice-protocol]: protocols-and-transports/ice-duplex-transports
 
-[IDuplexClientTransport]: csharp:IceRpc.Transports.IDuplexClientTransport
-[IDuplexServerTransport]: csharp:IceRpc.Transports.IDuplexServerTransport
-[IListener<IDuplexConnection>]: csharp:IceRpc.Transports.IListener-1
-[IDuplexConnection]: csharp:IceRpc.Transports.IDuplexConnection
+[`IDuplexClientTransport`]: csharp:IceRpc.Transports.IDuplexClientTransport
+[`IDuplexServerTransport`]: csharp:IceRpc.Transports.IDuplexServerTransport
+[`IListener<IDuplexConnection>`]: csharp:IceRpc.Transports.IListener-1
+[`IDuplexConnection`]: csharp:IceRpc.Transports.IDuplexConnection
 [Server]: csharp:IceRpc.Server
 [ConnectionCache]: csharp:IceRpc.ConnectionCache
 [ClientConnection]: csharp:IceRpc.ClientConnection

content/icerpc/ice-protocol/protocol-frames.md

@@ -216,4 +216,4 @@ set to 1.1.
 [protocol-and-encoding]: https://doc.zeroc.com/ice/3.7/ice-protocol-and-encoding
 [Slice]: /slice1
 [status-code]: ../invocation/incoming-response#status-code
-[request-fields]: ../invocation/outgoing-request#request-fields
+[request-fields]: ../invocation/outgoing-request#request-field

content/icerpc/invocation/outgoing-request.md

@@ -9,6 +9,7 @@ In order to make an RPC, you construct an outgoing request and then pass this re
 method of an [invoker](invocation-pipeline#the-invoker-abstraction).
 
 An outgoing request carries all the information an invoker needs to send a request:
+
 - the [service address](service-address) of the target service
 - the name of the operation to call on this service
 - request [fields](#request-fields)

content/icerpc/multiplexed-transport.md

@@ -42,11 +42,11 @@ See also [Security with TLS][security-with-tls] for additional information.
 The C# multiplexed transport abstraction consists of a number of interfaces that a custom transport needs to
 implement:
 
-- [IMultiplexedClientTransport]: a factory to create outgoing connections
-- [IMultiplexedServerTransport]: a factory to create listeners
-- [IListener<IMultiplexedConnection>]: a factory to listen for and create incoming connections
-- [IMultiplexedConnection]: a connection to accept and create streams
-- [IMultiplexedStream]: a stream to allow a client and server to communicate
+- [`IMultiplexedClientTransport`]: a factory to create outgoing connections
+- [`IMultiplexedServerTransport`]: a factory to create listeners
+- [`IListener<IMultiplexedConnection>`]: a factory to listen for and create incoming connections
+- [`IMultiplexedConnection`]: a connection to accept and create streams
+- [`IMultiplexedStream`]: a stream to allow a client and server to communicate
 
 The API documentation of these interfaces specifies the contract a custom transport needs to comply with.
 
@@ -62,11 +62,11 @@ To use a custom transport, the application needs to provide an instance of `IMul
 [full-duplex]: https://en.wikipedia.org/wiki/Duplex_(telecommunications)#Full_duplex
 [flow-control]: https://en.wikipedia.org/wiki/Flow_control_(data)
 
-[IMultiplexedClientTransport]: csharp:IceRpc.Transports.IMultiplexedClientTransport
-[IMultiplexedServerTransport]: csharp:IceRpc.Transports.IMultiplexedServerTransport
-[IListener<IMultiplexedConnection>]: csharp:IceRpc.Transports.IListener-1
-[IMultiplexedConnection]: csharp:IceRpc.Transports.IMultiplexedConnection
-[IMultiplexedStream]: csharp:IceRpc.Transports.IMultiplexedStream
+[`IMultiplexedClientTransport`]: csharp:IceRpc.Transports.IMultiplexedClientTransport
+[`IMultiplexedServerTransport`]: csharp:IceRpc.Transports.IMultiplexedServerTransport
+[`IListener<IMultiplexedConnection>`]: csharp:IceRpc.Transports.IListener-1
+[`IMultiplexedConnection`]: csharp:IceRpc.Transports.IMultiplexedConnection
+[`IMultiplexedStream`]: csharp:IceRpc.Transports.IMultiplexedStream
 [Server]: csharp:IceRpc.Server
 [ConnectionCache]: csharp:IceRpc.ConnectionCache
 [ClientConnection]: csharp:IceRpc.ClientConnection

content/icerpc/slic-transport/protocol-frames.md

@@ -12,10 +12,12 @@ Frames and types from this page are defined using [Slice].
 
 All the frames have a header and a body. The header layout is common to all Slic versions and is composed of the
 following fields:
+
 - a frame type defined as an `uint8` enumeration
 - a frame size defined as a `varuint62` representing the size of the frame body.
 
 The frame type is defined as follows:
+
 ```slice
 enum FrameType : uint8 {
     Initialize = 1

content/icerpc/slic-transport/streams.md

@@ -78,6 +78,7 @@ Reducing the maximum stream frame size reduces this delay. It's in particular us
 A stream has two separate state machines: one for its write-side and one for its read-side.
 
 The state machines also depend on the type of the stream. The type of a stream is defined as follows:
+
 - a local stream is a stream created by the application
 - a remote stream is a stream accepted by the application
 
@@ -183,5 +184,4 @@ peer that its done reading.
 [StreamLast]: protocol-frames#stream-and-streamlast-frames
 [StreamReadsClosed]: protocol-frames#streamreadsclosed-and-streamwritesclosed-frames
 [StreamWritesClosed]: protocol-frames#streamreadsclosed-and-streamwritesclosed-frames
-[StreamWindowUpdate]: protocol-frames#streamwindowupdate-frame
 [stream-concurrency]: flow-control#stream-concurrency

content/slice/encoding/constructed-types.md

@@ -45,20 +45,21 @@ compact enum StringInt32Result {
 {% /slice2 %}
 
 {% slice1 %}
+
 ## Sequence
 
 A sequence of N elements of type T is encoded as a [variable-length size][slice1-var-size] N followed by each element
 encoded in order.
 
-#### Example: empty sequence
+### Example: empty sequence
 
 An empty sequence is encoded as:
 
 ```
 0x00: size 0
 ```
 
-#### Example: sequence of int32
+### Example: sequence of int32
 
 A sequence of `int32` with values 5, 32 and 9 is encoded as:
 
@@ -68,23 +69,25 @@ A sequence of `int32` with values 5, 32 and 9 is encoded as:
 0x20 0x00 0x00 0x00: 32 over 4 bytes in little-endian order
 0x09 0x00 0x00 0x00: 9 over 4 bytes in little-endian order
 ```
+
 {% /slice1 %}
 
 {% slice2 %}
+
 ## Sequence with a non-optional element type
 
 A sequence of N elements with a non-optional element type T is encoded as a `varuint62`-encoded N followed by each
 element encoded in order.
 
-#### Example: empty sequence
+### Example: empty sequence
 
 An empty sequence is encoded as:
 
 ```
 0x00: size 0
 ```
 
-#### Example: sequence of int32
+### Example: sequence of int32
 
 A sequence of `int32` with values 5, 32 and 9 is encoded as:
 
@@ -100,7 +103,7 @@ A sequence of `int32` with values 5, 32 and 9 is encoded as:
 A sequence of N elements with a optional element type T? is encoded as a varuint62-encoded N followed by a
 [bit sequence][bit-sequence] with N bits, followed by each element with a value encoded in order.
 
-#### Example: sequence of int32?
+### Example: sequence of int32?
 
 A sequence of `int32?` with values 5, no-value, 9 and no-value is encoded as:
 

content/slice/encoding/operation.md

@@ -20,6 +20,7 @@ Unlike the encoding of tagged fields in classes, the encoding of tagged argument
 {% /slice1 %}
 
 {% slice2 %}
+
 ## Non-stream encoding
 
 The arguments of an operation are encoded as a [segment]. The body of this segment corresponds to a virtual [struct]

content/slice/encoding/primitive-types.md

@@ -4,6 +4,7 @@ description: Learn how primitive types are encoded with Slice.
 ---
 
 {% slice1 %}
+
 ## AnyClass
 
 `AnyClass` is an abstract type. When you encode or decode a parameter or field with type `AnyClass`, you are encoding
@@ -15,6 +16,7 @@ or decoding a concrete class instance using the [class encoding/decoding rules](
 A `bool` is encoded on a single byte, where 0 means `false` and 1 means `true`. Other values are invalid.
 
 {% slice2 %}
+
 ## Fixed-size integral types
 
 | Type          | Encoded on N bytes |