From 486b5e8fed38090643a6721c8c3a15b4bd0ce46e Mon Sep 17 00:00:00 2001 From: Victor Adossi Date: Fri, 29 Aug 2025 19:33:55 +0900 Subject: [PATCH 1/3] feat: document code fragment rules This commit adds a basic style guide to the contributing documentation, with rules around how we currently do executable code fragments. Resolves #239 --- CONTRIBUTING.md | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e347452f..518aab7c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ The Component Model documentation is a [Bytecode Alliance](https://bytecodeallia You can run the website locally using the [mdBook](https://rust-lang.github.io/mdBook/index.html) command line tool. -### Prerequisites +## Prerequisites To use this repository, you need [mdBook](https://rust-lang.github.io/mdBook/guide/installation.html) installed on your workstation. @@ -20,7 +20,7 @@ cargo install --version 0.7.7 mdbook-linkcheck [cargo]: https://doc.rust-lang.org/cargo -### Running the website locally +## Running the website locally After installing mdBook, you'll need to clone the code via git and navigate to the directory. @@ -52,6 +52,28 @@ mdbook build Don't forget to remove the changes in `book.toml` before you commit! +## Writing style guide + +This section contains what is a *somewhat loosely* applied style guide for writing that is contributed to `component-docs`. + +### Executable code fragments + +For code that should be executed by the user in their console of choice, prefer using `sh`/`bash`. While not every user's +shell is `sh` or `bash` (with `zsh` being incredilby common), `sh`/`bash` provide a decent approximation. + +Importantly, code that is meant to be executed should be copy-pastable -- and should not contain `$` as a prefix. For example: + +```sh +echo 'this is an example'; +``` + +On the other hand, when commands *and* output are shown, use `console` and *do* prefix the command with `$` to differentiate it (or `#` in a sudo context): + +```console +$ echo 'this is an example'; +this is an example +``` + ## Submitting Changes You can click the Fork button in the upper-right area of the screen to create a copy of this repository in your GitHub account. This copy is called a fork. Make any changes you want in your fork, and when you are ready to submit those changes, go to your fork and create a new pull request to let us know about it. From 1f1beffc1c84e09a0d18550d7c8f9a50457cc033 Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Mon, 8 Sep 2025 09:33:03 +0900 Subject: [PATCH 2/3] revert: header level in contributing --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 518aab7c..05c4463d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ The Component Model documentation is a [Bytecode Alliance](https://bytecodeallia You can run the website locally using the [mdBook](https://rust-lang.github.io/mdBook/index.html) command line tool. -## Prerequisites +### Prerequisites To use this repository, you need [mdBook](https://rust-lang.github.io/mdBook/guide/installation.html) installed on your workstation. From 11a7e6589b0d79af6ed20313f97efed5552e9010 Mon Sep 17 00:00:00 2001 From: Victor Adossi <123968127+vados-cosmonic@users.noreply.github.com> Date: Mon, 8 Sep 2025 11:29:45 +0900 Subject: [PATCH 3/3] revert: change to section header --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 05c4463d..648e0c66 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,7 +20,7 @@ cargo install --version 0.7.7 mdbook-linkcheck [cargo]: https://doc.rust-lang.org/cargo -## Running the website locally +### Running the website locally After installing mdBook, you'll need to clone the code via git and navigate to the directory.