From 2f1ff61a0e2aabdb705f27a4ed6b60a7f9f7674f Mon Sep 17 00:00:00 2001 From: Kara Date: Tue, 12 Sep 2023 02:56:33 -0500 Subject: [PATCH] move readme content to the docs site itself, and link it --- README.md | 40 +------------- ...ownload.png => meta-artifact-download.png} | Bin src/en/meta/guide-to-editing-docs.md | 51 +++++++++++++++++- 3 files changed, 50 insertions(+), 41 deletions(-) rename src/en/assets/images/{readme-artifact-download.png => meta-artifact-download.png} (100%) diff --git a/README.md b/README.md index d19969a78..43c3b3a9c 100644 --- a/README.md +++ b/README.md @@ -19,45 +19,7 @@ The following `mdbook` features & plugins are available and in use: The site is currently hosted at [https://spacestation14.io/docs/](https://spacestation14.io/docs/). This will likely change in the future, so links here should not be relied on. -## Building - -Necessary dependencies are Rust, as well as `mdbook` and the plugins listed above, installed using cargo. - -Call `mdbook serve` to build and locally host the documentation from the `book` directory. - -## Contributing & porting pages - -To port a page, you'll need write access to `docs.spacestation14.io` (old wiki.js), or find some way to view MD source idk. - -1. Find a page with the `Porting` template on the top -2. Find the corresponding page in Wiki.js -- it should just have the same name -3. Copy over the Wiki.js markdown -4. Change any relative links to point to their correct corresponding -5. Change any self-hosted or imgur images to be hosted in `src/en/assets` instead -6. Adjust any admonishments as follows: - `````` - > etc text example - {.is-(danger/warning/info/example)} - `````` - to - `````` - ```admonish danger/warning/info/example "Title Text Or Leave blank etc" - etc text example - ``` - `````` -7. Add a redirect for the original wiki.js link to the new `src/SUMMARY.md` link in `book.toml`--follow the example. You'll need to add `/index.html` after the wiki.js link for it to redirect properly. - -## Testing changes - -If you've made a PR, the easiest way to test your changes, since they're just markdown, is to view them in GitHub's own markdown viewer in the `Files changed` tab. You can also use a local markdown previewer extension for something like [VSCode](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced). - -If you want a slightly more authentic experience, every PR will have the `Test mdBook Build & Upload Artifact` action run, and you can download the built site like so: - -![](src/en/assets/images/readme-artifact-download.png) - -Then, just unzip it and open `index.html`. Our custom CSS and stuff won't work super well but it'll look good enough. - -For an authentic-authentic experience, just follow the build instructions above and run `mdbook serve` like normal. +**For information such as how to edit, build & test these docs, see [Guide to Editing Docs](https://spacestation14.io/docs/en/meta/guide-to-editing-docs.html). on the site itself** (or [in this repo](./src/en/meta/guide-to-editing-docs.md)) ## Screenshots diff --git a/src/en/assets/images/readme-artifact-download.png b/src/en/assets/images/meta-artifact-download.png similarity index 100% rename from src/en/assets/images/readme-artifact-download.png rename to src/en/assets/images/meta-artifact-download.png diff --git a/src/en/meta/guide-to-editing-docs.md b/src/en/meta/guide-to-editing-docs.md index d6fec4cc3..aaa439f69 100644 --- a/src/en/meta/guide-to-editing-docs.md +++ b/src/en/meta/guide-to-editing-docs.md @@ -6,7 +6,9 @@ There are a couple things to keep in mind when contributing. While we disallow w If you want to get an idea of what features are at your disposal when writing documentation, go to our [Docs Example Page](./docs-example-page.md). -To start a basic edit of a page, simply follow these steps: +## Making basic edits + +If you just want to make a basic edit of a page, simply follow these steps--you dont need any of the fancy stuff talked about later: 1. Create an accout on GitHub, or log in if you already have one. @@ -24,4 +26,49 @@ To start a basic edit of a page, simply follow these steps: 5. Make your changes, then commit & create a pull request! We'll handle the rest. -More in-depth information for contributors, like how to test locally & port pages from our old docs site, is available on our [README](https://github.com/space-wizards/docs/blob/master/README.md) for the GitHub docs site. \ No newline at end of file +## Building + +If you want to locally build the docs, the necessary dependencies are Rust and some binaries installed using `cargo`. It's recommended that you use `cargo binstall` or `cargo quickinstall`, as building can take a while. + +From cargo, install: +- `mdbook` +- `mdbook-mermaid` +- `mdbook-template` +- `mdbook-linkcheck` +- `mdbook-admonish` + +Call `mdbook serve` to build and locally host the documentation from the `book` directory at `localhost:3000`. + +## Porting pages from Wiki.js + +To port a page, you'll need write access to `docs.spacestation14.io` (old wiki.js), or find some way to view MD source idk. + +1. Find a page with the `Porting` template on the top +2. Find the corresponding page in Wiki.js -- it should just have the same name +3. Copy over the Wiki.js markdown +4. Change any relative links to point to their correct corresponding +5. Change any self-hosted or imgur images to be hosted in `src/en/assets` instead +6. Adjust any admonishments as follows: + `````` + > etc text example + {.is-(danger/warning/info/example)} + `````` + to + `````` + ```admonish danger/warning/info/example "Title Text Or Leave blank etc" + etc text example + ``` + `````` +7. Add a redirect for the original wiki.js link to the new `src/SUMMARY.md` link in `book.toml`--follow the example. You'll need to add `/index.html` after the wiki.js link for it to redirect properly. + +## Testing changes + +If you've made a PR, the easiest way to test your changes, since they're just markdown, is to view them in GitHub's own markdown viewer in the `Files changed` tab. You can also use a local markdown previewer extension for something like [VSCode](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced). + +If you want a slightly more authentic experience, every PR will have the `Test mdBook Build & Upload Artifact` action run, and you can download the built site like so: + +![](../assets/images/meta-artifact-download.png) + +Then, just unzip it and open `index.html`. Our custom CSS and stuff won't work super well but it'll look good enough. + +For an authentic-authentic experience, just follow the build instructions above and run `mdbook serve` like normal.