docs: Fix minor style/grammar issues in markdown files (#1931)

The docs were somewhat inconsistent with markdown formatting which
should be mostly cleaned up now.

The cleanup was focused on the libsql specific docs (meaning all
markdown files except in the `vendored`, `libsql-sqlite3`, and
`libsql-ffi/bundled` directories)

A `.markdownlint.yaml` file was also added to help with maintenance in
the future.

Prose should be mostly identical except for fixing grammar issues.

Author: penberg

.markdownlint.yaml

@@ -0,0 +1,25 @@
+# Default state for all rules
+default: true
+
+# MD010/no-hard-tabs : Hard tabs : https://github.com/DavidAnson/markdownlint/blob/v0.37.3/doc/md010.md
+MD010:
+  # Include code blocks
+  code_blocks: false
+  # Fenced code languages to ignore
+  ignore_code_languages: []
+  # Number of spaces for each hard tab
+  spaces_per_tab: 4
+
+# MD013/line-length : Line length : https://github.com/DavidAnson/markdownlint/blob/v0.37.3/doc/md013.md
+MD013: false
+
+# MD024/no-duplicate-heading : Multiple headings with the same content : https://github.com/DavidAnson/markdownlint/blob/v0.37.3/doc/md024.md
+MD024:
+  # Only check sibling headings
+  siblings_only: true
+
+# MD033/no-inline-html : Inline HTML : https://github.com/DavidAnson/markdownlint/blob/v0.37.3/doc/md033.md
+MD033:
+  # Allowed elements
+  allowed_elements:
+    - p

CODE_OF_CONDUCT.md

@@ -61,7 +61,7 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-<a href="mailto:[email protected]">[email protected]</a>.
+[[email protected]](mailto:[email protected]).
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the
@@ -131,4 +131,3 @@ For answers to common questions about this code of conduct, see the FAQ at
 [Mozilla CoC]: https://github.com/mozilla/diversity
 [FAQ]: https://www.contributor-covenant.org/faq
 [translations]: https://www.contributor-covenant.org/translations
-

CONTRIBUTING.md

@@ -4,48 +4,51 @@ Thank you for your interest in contributing to libsql! We welcome contributions
 
 Before you start, please take a moment to review the guidelines outlined below.
 
-# Code of Conduct
+## Code of Conduct
 
 Please note that we have a Code of Conduct in place to ensure a positive and inclusive environment for everyone involved.
 
-Getting Started
-
-Fork the repository.
-Clone your forked repository to your local machine.
-Create a new branch for your feature or bug fix: git checkout -b feature-name.
-Make your changes and test thoroughly.
-Commit your changes with descriptive commit messages.
-Push your changes to your forked repository: git push origin feature-name.
-Submit a pull request to the main branch of the original repository.
-Contribution Guidelines
-
-All contributions should be well-documented and follow the existing code style.
-Include tests for any new functionality or bug fixes.
-Update documentation as necessary, including any relevant README or usage guides.
-Maintain backward compatibility whenever possible.
-Follow the Git commit message guidelines for consistent commit messages.
-Review the existing issues and pull requests to avoid duplicating efforts.
-Pull Request Process
-
-Ensure that your pull request addresses a specific issue. If there isn't an issue, consider creating one first.
-Clearly describe the problem or feature in your pull request and reference the relevant issue.
-Provide steps to reproduce and test your changes if applicable.
-Ensure that your branch is up-to-date with the latest changes from the main branch.
-All checks (tests, formatting, etc.) must pass before your pull request can be merged.
-After addressing review comments, your pull request will be merged by a project maintainer.
-Documentation
+### Getting Started
+
+* Fork the repository.
+* Clone your forked repository to your local machine.
+* Create a new branch for your feature or bug fix: `git checkout -b feature-name`.
+* Make your changes and test thoroughly.
+* Commit your changes with descriptive commit messages.
+* Push your changes to your forked repository: `git push origin feature-name`.
+* Submit a pull request to the main branch of the original repository.
+
+### Contribution Guidelines
+
+* All contributions should be well-documented and follow the existing code style.
+* Include tests for any new functionality or bug fixes.
+* Update documentation as necessary, including any relevant README or usage guides.
+* Maintain backward compatibility whenever possible.
+* Follow the Git commit message guidelines for consistent commit messages.
+* Review the existing issues and pull requests to avoid duplicating efforts.
+
+### Pull Request Process
+
+* Ensure that your pull request addresses a specific issue.
+  * If there isn't an issue, consider creating one first.
+* Clearly describe the problem or feature in your pull request and reference the relevant issue.
+* Provide steps to reproduce and test your changes if applicable.
+* Ensure that your branch is up-to-date with the latest changes from the main branch.
+* All checks (tests, formatting, etc.) must pass before your pull request can be merged.
+* After addressing review comments, your pull request will be merged by a project maintainer.
+
+### Documentation
 
 Help us improve the project's documentation by fixing typos, clarifying language, or adding missing information. Documentation improvements can be submitted as pull requests.
 
-Reporting Issues
+### Reporting Issues
 
 If you encounter a bug or have a suggestion for the project, please open an issue using the provided issue template. Include as much detail as possible to help us understand and address the problem.
 
-Getting Help
+### Getting Help
 
 If you need assistance, have questions, or want to discuss ideas, you can:
 
 Join our Discord server and chat with the community.
 Mention @maintainer in your issue or pull request for a faster response from project maintainers.
 We appreciate your time and effort in contributing to libsql!
-

README-libsql.md

@@ -13,7 +13,7 @@ This libSQL API is an experimental, batteries-included library built on top of S
 
 ## Getting Started
 
-* [Rust](core) 
+* [Rust](core)
 * [Python](https://github.com/libsql/libsql-experimental-python)
 * [JavaScript](https://github.com/libsql/libsql-experimental-node)
 * [Go](https://github.com/libsql/go-libsql)

README.md

@@ -1,3 +1,5 @@
+<!-- markdownlint-disable MD033 MD041 -->
+
 <p align="center">
   <a href="https://turso.tech/libsql">
     <img alt="libSQL by Turso" src="https://github.com/tursodatabase/libsql/assets/950181/6c8679e7-65a9-4777-b08a-2ddf4321160f" width="1000">
@@ -33,7 +35,7 @@
 
 ## Documentation
 
-We aim to evolve it to suit many more use cases than SQLite was originally designed for, and plan to use third-party OSS code wherever it makes sense. 
+We aim to evolve it to suit many more use cases than SQLite was originally designed for, and plan to use third-party OSS code wherever it makes sense.
 
 libSQL has many great features, including:
 
@@ -54,19 +56,22 @@ The comprehensive description can be found [here](libsql-sqlite3/doc/libsql_exte
 ### Official Drivers
 
 * [TypeScript / JS](https://github.com/tursodatabase/libsql-client-ts)
-* [Rust](libsql) 
+* [Rust](libsql)
 * [Go](https://github.com/tursodatabase/go-libsql)
 * [Go (no CGO)](https://github.com/tursodatabase/libsql-client-go)
 
 ### Experimental Drivers
+
 * [Python](https://github.com/tursodatabase/libsql-experimental-python) (experimental)
 * [C](bindings/c) (experimental)
 
 ### Community Drivers
+
 * [PHP](https://github.com/tursodatabase/turso-client-php)
 * [D](https://github.com/pdenapo/libsql-d) (experimental, based on the C driver)
 
 ### GUI Support
+
 * [Beekeeper Studio](https://www.beekeeperstudio.io/db/libsql-client/) &mdash; macOS, Windows, and Linux
 * [Outerbase](https://www.outerbase.com) &mdash; Runs in the browser
 * [TablePlus](https://tableplus.com) &mdash; macOS, Windows, and Linux
@@ -95,6 +100,7 @@ libsql>
 ```
 
 ### Docker
+
 To run libSQL using docker, refer to the [Docker Docs](docs/DOCKER.md)
 
 ## Why a fork?
@@ -105,15 +111,15 @@ But despite having its code available, SQLite famously doesn't accept external c
 
 There have been other forks in the past, but they all focus on a specific technical difference. We aim to be a community where people can contribute from many different angles and motivations.
 
-We want to see a world where everyone can benefit from all of the great ideas and hard work that the SQLite community contributes back to the codebase. Community contributions work well, because we’ve done it before. If this was possible, what do you think SQLite could become?
+We want to see a world where everyone can benefit from all the great ideas and hard work that the SQLite community contributes back to the codebase. Community contributions work well, because we’ve done it before. If this was possible, what do you think SQLite could become?
 
 You can read more about our goals and motivation in our [product vision](https://turso.tech/libsql-manifesto).
 
 ## Compatibility with SQLite
 
 Compatibility with SQLite is of great importance for us. But it can mean many things. So here's our stance:
 
-* **The file format**: libSQL will always be able to ingest and write the SQLite file format. We would love to add extensions like encryption, and CRC that require the file to be changed. But we commit to always doing so in a way that generates standard sqlite files if those features are not used.
+* **The file format**: libSQL will always be able to ingest and write the SQLite file format. We would love to add extensions like encryption, and CRC that require the file to be changed. But we commit to always doing so in a way that generates standard SQLite files if those features are not used.
 * **The API**: libSQL will keep 100% compatibility with the SQLite API, but we may add additional APIs.
 * **Embedded**: SQLite is an embedded database that can be consumed as a single .c file with its accompanying header. libSQL will always be embeddable, meaning it runs inside your process without needing a network connection. But we may change the distribution, so that object files are generated, instead of a single .c file.
 

bindings/wasm/README.md

@@ -2,7 +2,7 @@
 
 ## Developing
 
-```
+```console
 wasm-pack build --target nodejs
 node example.js
 ```

bottomless/README.md

@@ -1,40 +1,51 @@
 # Bottomless S3-compatible virtual WAL for libSQL
-##### Work in heavy progress!
+
+## Work in heavy progress
 
 This project implements a virtual write-ahead log (WAL) which continuously backs up the data to S3-compatible storage and is able to restore it later.
 
 ## How to build
-```
+
+```shell
 LIBSQL_DIR=/path/to/your/libsql/directory make
 ```
+
 will produce a loadable `.so` libSQL extension with bottomless WAL implementation.
-```
+
+```shell
 LIBSQL_DIR=/path/to/your/libsql/directory make release
 ```
+
 will do the same, but for release mode.
 
 ## Configuration
-By default, the S3 storage is expected to be available at `http://localhost:9000` (e.g. a local development [minio](https://min.io) server), and the auth information is extracted via regular S3 SDK mechanisms, i.e. environment variables and `~/.aws/credentials` file, if present. Ref: https://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/guide_credentials_environment.html
+
+By default, the S3 storage is expected to be available at `http://localhost:9000` (e.g. a local development [minio](https://min.io) server), and the auth information is extracted via regular S3 SDK mechanisms, i.e. environment variables and `~/.aws/credentials` file, if present. Ref: <https://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/guide_credentials_environment.html>
 
 Default endpoint can be overridden by an environment variable too, and in the future it will be available directly from libSQL as an URI parameter:
-```
+
+```shell
 export LIBSQL_BOTTOMLESS_ENDPOINT='http://localhost:9042'
 ```
 
 Bucket used for replication can be configured with:
-```
+
+```shell
 export LIBSQL_BOTTOMLESS_BUCKET='custom-bucket'
 ```
 
 On top of that, bottomless is implemented on top of the official [Rust SDK for S3](https://crates.io/crates/aws-sdk-s3), so all AWS-specific environment variables like `AWS_DEFAULT_REGION`, `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` also work, as well as the `~/.aws/credentials` file.
 
 ## How to use
+
 From libSQL shell, load the extension and open a database file with `bottomless` WAL, e.g.:
+
 ```sql
 .load ../target/debug/bottomless
 .open file:test.db?wal=bottomless
 PRAGMA journal_mode=wal;
 ```
+
 Remember to set the journaling mode to `WAL`, which needs to be done at least once, before writing any content, otherwise the custom WAL implementation will not be used.
 
 In order to customize logging, use `RUST_LOG` env variable, e.g. `RUST_LOG=info ./libsql`.
@@ -46,14 +57,18 @@ LIBSQL_DIR=/path/to/your/libsql/directory make test
 ```
 
 ## CLI
+
 The command-line interface supports browsing, restoring and removing snapshot generations.
 It can be installed as a standalone executable with:
+
 ```sh
 RUSTFLAGS="--cfg uuid_unstable" cargo install bottomless-cli
 ```
+
 Alternatively, bottomless-cli is available from the repository by running `cargo run`.
 Available commands:
-```
+
+```console
 $ bottomless-cli --help
 Bottomless CLI
 
@@ -75,8 +90,9 @@ Options:
 ### Examples
 
 #### Listing generations
-```
-[sarna@sarna-pc test]$ bottomless-cli -e http://localhost:9000 ls -v -l3
+
+```console
+$ bottomless-cli -e http://localhost:9000 ls -v -l3
 e4eb3c21-ff53-7b2e-a6ea-ca396f4df9b1
 	created at (UTC):     2022-12-23 08:24:52.500
 	change counter:       [0, 0, 0, 51]
@@ -106,7 +122,8 @@ e4eb3c22-0941-73eb-85df-4e8552a0e88c
 ```
 
 #### Restoring the database
-```
+
+```console
 $ RUST_LOG=info bottomless-cli -e http://localhost:9000 restore
 2022-12-23T10:16:10.703557Z  INFO bottomless::replicator: Bucket bottomless exists and is accessible
 2022-12-23T10:16:10.709526Z  INFO bottomless_cli: Database: test.db
@@ -115,20 +132,24 @@ $ RUST_LOG=info bottomless-cli -e http://localhost:9000 restore
 ```
 
 #### Removing old snapshots
-```
+
+```console
 $ bottomless-cli -e http://localhost:9000 rm -v --older-than 2022-12-15
 Removed 4 generations
 ```
 
 ## Details
+
 All page writes committed to the database end up being asynchronously replicated to S3-compatible storage.
 On boot, if the main database file is empty, it will be restored with data coming from the remote storage.
 If the database file is newer, it will be uploaded to the remote location with a new generation number.
 If a local WAL file is present and detected to be newer than remote data, it will be uploaded as well.
 
 ### Tests
+
 A fully local test can be performed by using a local S3-compatible server, e.g. [Minio](https://min.io/). Assuming the server is available at HTTP port 9000,
 you can use the following scripts:
+
 ```sh
 cd test/
 export LIBSQL_BOTTOMLESS_ENDPOINT=http://localhost:9000

docs/ADMIN_API.md

@@ -5,29 +5,33 @@ This document describes the admin API endpoints.
 The admin API is used to manage namespaces on a `sqld` instance. Namespaces are isolated database within a same sqld instance.
 
 To enable the admin API, and manage namespaces, two extra flags need to be passed to `sqld`:
+
 - `--admin-listen-addr <addr>:<port>`: the address and port on which the admin API should listen. It must be different from the user API listen address (whi defaults to port 8080).
 - `--enable-namespaces`: enable namespaces for the instance. By default namespaces are disabled.
 
 ## Routes
 
-```
+```HTTP
 POST /v1/namespaces/:namespace/create
 ```
+
 Create a namespace named `:namespace`.
 body:
+
 ```json
 {
     "dump_url"?: string,
 }
 ```
 
-```
+```HTTP
 DELETE /v1/namespaces/:namespace
 ```
 
 Delete the namespace named `:namespace`.
 
-```
+```HTTP
 POST /v1/namespaces/:namespace/fork/:to
 ```
+
 Fork `:namespace` into new namespace `:to`

docs/BUILD-RUN.md

@@ -22,8 +22,9 @@ You can query sqld using one of the provided [client
 libraries](../libsql-server#client-libraries).
 
 You can also use the [turso cli](https://docs.turso.tech/reference/turso-cli) to connect to the sqld instance:
-```
-turso db shell http://127.0.0.1:8080    
+
+```console
+turso db shell http://127.0.0.1:8080
 ```
 
 ## Download a prebuilt binary
@@ -59,7 +60,7 @@ sqld --help
 ## Using a prebuilt Docker image
 
 The sqld release process publishes a Docker image to the GitHub Container
-Registry. The URL is https://ghcr.io/tursodatabase/libsql-server. You can run the latest image locally
+Registry. The URL is <https://ghcr.io/tursodatabase/libsql-server>. You can run the latest image locally
 on port 8080 with the following:
 
 ```bash
@@ -194,7 +195,5 @@ development.
 cargo xtask test
 ```
 
-
-[sqld releases page]: https://github.com/libsql/sqld/releases
 [sqld container release tags]: https://github.com/libsql/sqld/pkgs/container/sqld
 [sqld release tags]: https://github.com/libsql/sqld/releases