diff --git a/README.md b/README.md index d8f98dd5..e9bb96f4 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,8 @@ If you are looking for the officially run Strata Source Wiki, please go here: ht ## Getting Started +Before you begin, if you are wishing to contribute documentation changes to this repository, you will need to [fork this repository](https://github.com/StrataSource/Wiki/fork). This allows you to open a Pull Request targeting the `main` branch for review. The same goes for working with the Wiki software except making a Pull Request in that repository instead. + Node.js is required to run the Strata Source Wiki. If you do not have it installed, please go to the Node.js download page here: https://nodejs.org/en/download/ To start the Wiki, run the following: diff --git a/docs/contribute/advanced/creating-category.md b/docs/contribute/advanced/creating-category.md new file mode 100644 index 00000000..8ba2bc2e --- /dev/null +++ b/docs/contribute/advanced/creating-category.md @@ -0,0 +1,46 @@ +--- +title: Making A New Category +weight: 10 +--- + +# Making A New Category + +Categories are the top level groups you can see on the home page of the Strata Source Wiki. Ex. Panorama, Materials, Entities. These categories contain topics relating to the category and from there articles for each topic. + +![Wiki Home Categories](../imgs/home-page.png) + +Currently as of writing (1/12/26), Wiki categories are unfortunately controlled by the Wiki software, rather than simply making a folder, a `meta.json` file, and the Markdown articles, this is planned to hopefully change in the future. + +Before making a new category, a Markdown file and a `meta.json` file is needed to make an category work. Check out the [Category section](../basics/structure#categories) of the `Wiki Structure` article to know how the Wiki is fully structured and how to set up the `meta.json` file. + +Once the files and folders setup in the `docs` folder, head to the `site/src/routes/+page.svelte` file. This file is the page file for the `Home` page of the Wiki. + +## Adding The Category + +The area that should be focused in this file is the line that starts with `const categories: (`. This line is the beginning of the list of all the categories features on the `Home` page. A few lines down should describe how each section should be structured to provide the information needed to tell the software what the category itself is. + +There are two parts to the list of categories, the categories themselves, and header separators. Separators are simply the bigger text that separates the categories out, ex. "Reference", "Scripting", "Contributing". + +The easy thing to do is copy and paste a preexisting category or header separator that is already in the `categories` list. Do note, order does matter here, categories first on the list will be at the top of the page. + +### Category + +```ts + { + id: string; // The article (without the ".md") that should be entered into by default when the category is selected. + title: string; // Title displayed for the category. + description: string; // Description of the category. + icon: string; // Icon to use for the category displayed before the "title". Recommended to use a icon imported from the material icons package. + separation: false; // This needs to be false for categories. + } +``` + +### Header Separator + +```ts +{ title: string; separation: true; } // Alternate structure for headers separators. +``` + +## Testing Changes + +If the local instance of the Wiki is currently running, once a change is made to the file, the changes will be automatically applied live for checking if changes appear correctly. Svelte will display a error if there is a issue with the file that has been edited. diff --git a/docs/contribute/advanced/getting-started.md b/docs/contribute/advanced/getting-started.md new file mode 100644 index 00000000..e602b1e2 --- /dev/null +++ b/docs/contribute/advanced/getting-started.md @@ -0,0 +1,34 @@ +--- +title: Getting Started With The Wiki Software +weight: 0 +--- + +# Getting Started With The Wiki Software + +This Wiki topic assumes that you understand how to work with TypeScript, SCSS, HTML, Svelte, as well as Git submodules. The Wiki software is a submodule separate from the documentation. + +If you followed the instructions from [Getting Started](../basics/getting-started), then the Wiki software should already be setup correctly. However, if you wish to contribute to the Wiki software, you will need to make a fork of the repository so an Pull Request can be created. From there, you must redirect the remote URL for the Wiki software submodule to use your fork so you can use your software changes with the Wiki documentation. + +## Editors & Extensions + +The recommended editor for editing both the Wiki documentation and/or the Wiki software is [Visual Studio Code](https://code.visualstudio.com/). Below are a few extensions you can install to help with working the repository: + +[`markdownlint`](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) By David Anson: A extension for Markdown linting and style checking. + +[`Svelte for VS Code`](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode) By Svelte: The official language support extension. + +[`ESLint`](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) By Microsoft: A linter for both JavaScript and TypeScript code. + +[`Code Spell Checker`](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) By Street Side Software: A basic spellchecker for both code and other files. + +## File Structure + +The Wiki software file structure is much more complex than the Wiki documentation. The folder that will be worked with the most is the `src` folder which contains everything that drives the Wiki. Nothing else should be touched unless you know what you are doing. + +`lib`: Where some site assets belong, where various components like buttons, Markdown notices, and more are structure, as well as where the dump parsers live. + +`routes`: Contains the TypeScript and Svelte files used to structure and make the Wiki function. Ex. page footers, categories, CSS formatting, HTML structure, etc. + +## What's Next + +Once you are setup and you understand what each folder in Wiki software is for, feel free to check out the other articles in the `Advanced` section of the `Contribution` topic. diff --git a/docs/contribute/advanced/meta.json b/docs/contribute/advanced/meta.json index 4135376d..522b08ee 100644 --- a/docs/contribute/advanced/meta.json +++ b/docs/contribute/advanced/meta.json @@ -1,4 +1,4 @@ { "title": "Advanced", - "weight": 50 + "weight": 10 } diff --git a/docs/contribute/advanced/structure.md b/docs/contribute/advanced/structure.md deleted file mode 100644 index 133035fa..00000000 --- a/docs/contribute/advanced/structure.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Wiki Structure ---- - -# Wiki Structure - -The wiki is structured on 3 levels: - -- Category -- Topic -- Article - -## Categories - -Categories group articles together by a specific feature set, like Panorama UI. - -Categories are located inside the [`docs` folder](https://github.com/StrataSource/Wiki/tree/main/docs) in the repo and all contain a `meta.json` file. This file includes all information needed about the category, like it's title: - -```json -{ - "title": "Contribute" -} -``` - -## Topics - -Topics, also knows as Subcategories, divide categories into different sections like `Overview`, `Controls` and `Reference`. - -Topics are folders inside categories and also have their own `meta.json` file: - -```json -{ - "title": "Basics", - "weight": 10 -} -``` - -The `weight` property is optional and tells the wiki how to sort the topics: Bigger weight means a topic will move further down. If no weight is specified, the wiki will default to infinite weight, making the topic appear at the bottom of the list. - -## Articles - -Articles are the pages that make up the content of the wiki. Most articles are written by hand, but some are automatically generated from engine dumps and enhanced by manually written content. - -Articles that are fully manually written can be found as Markdown files inside topics. You can read about how these files are structured in [Editing Articles](../basics/editing-articles). diff --git a/docs/contribute/basics/creating-editing-articles.md b/docs/contribute/basics/creating-editing-articles.md new file mode 100644 index 00000000..d5ce67ac --- /dev/null +++ b/docs/contribute/basics/creating-editing-articles.md @@ -0,0 +1,75 @@ +--- +title: Creating & Editing Articles +weight: 10 +--- + +# Creating & Editing Articles + +## Creating An Article + +Articles on the Strata Source Wiki consist of Markdown files that work with the [standard set of syntax](https://www.markdownguide.org/basic-syntax/). + +The Wiki also follows some, but not all, of [GitHub's Markdown styling formats](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) (Ex. Alerts/Notices). + +All the Markdown files on the Wiki are inside topics. Topics are the folders that make up certain sections of categories. Example of `Category/Topic/Article`: `Audio/Overview/Sound System`. These Markdown files are placed into where they should displayed in the Wiki. + +For example, to add a article to the "Overview" topic in the "Panorama" category, all that needs to be done is to make a new Markdown file in the `docs/panorama/overview` folder. + +For more information on the Wiki's structure, please read [Wiki Structure](./structure). + +> [!WARNING] +> Markdown file names should be named close to the title of the article as well as not containing any spaces or special characters with the exception of dashes ("-") to replace spaces. +> Example: `article-title-here.md`. +> +> The same should go for creating new topic folders, keep it simple and understandable. +> +> The Wiki may not function correctly if it can't properly read the Markdown file name. + +## Meta Block + +Every article starts with a meta block like this: + +```yaml +--- +title: VScript Introduction +weight: 5 +features: + - USE_VSCRIPT +--- +``` + +It contains metadata about the article currently being viewed, like the title to display in the sidebar, the weight used for sorting or the [features flags](feature-flags) required for this page to be considered supported. + +## Top Level Heading + +By default no heading will be shown, **even if the `title` property is specified**. To make sure the user knows what the article is about, include a top level heading directly after the meta block like this: + +```md +# VScript Introduction +``` + +While this doesn't need to be the same as the one specified in the `title` property, it is generally recommended for them to be same. + +## Writing The Article + +After that follows the article content that'll get shown on the page. What is written usually doesn't follow a specific pattern. + +## Adding Links To Articles + +If another article needs to be linked in the Wiki, the path to the article Markdown file must be used without the extension. Relative paths can also be used instead of the full file path if desired. + +```md +[Insert Article Here](./my-fantastic-article) +``` + +To add a link to other categories or topics on the Wiki, the same method is used, simply include the full or relative path. + +```md +[Here's A Great topic](category/a-not-so-great-topic) +``` + +To add a link to a specific heading inside an article, add a `#` followed by the header title. The best way to get the link to the needed header is to hover over the header in the Wiki itself and click the `#` next to it. The link will be automatically copied to the clipboard for pasting. + +```md +[Something Random](vscript/reference/Globals#randomint) +``` diff --git a/docs/contribute/basics/editing-articles.md b/docs/contribute/basics/editing-articles.md deleted file mode 100644 index 2edf7de4..00000000 --- a/docs/contribute/basics/editing-articles.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Editing Articles -weight: 10 ---- - -# Editing Articles - -## Meta Block - -Every article starts with a meta block like this: - -```yaml ---- -title: VScript Introduction -weight: 5 -features: - - USE_VSCRIPT ---- -``` - -It contains metadata about the article you're currently viewing, like the title to display in the sidebar, the weight used for sorting or the [features flags](feature-flags) required for this page to be considered supported. - -## Top Level Heading - -By default no heading will be shown, **even if you specified the `title` property**. To make sure the user knows what the article is about, include a top level heading directly after the meta block like this: - -```md -# VScript Introduction -``` - -While this doesn't need to be the same as the one you specified in the `title` property, it is generally recommended for them to be same. - -## Writing The Article - -After that follows the article content that'll get shown on the page and usually doesn't follow a specific pattern. diff --git a/docs/contribute/basics/feature-flags.md b/docs/contribute/basics/feature-flags.md index 5f73b0b6..cb3b3b41 100644 --- a/docs/contribute/basics/feature-flags.md +++ b/docs/contribute/basics/feature-flags.md @@ -1,21 +1,21 @@ --- title: Feature Flags -weigth: 20 +weight: 30 --- # Feature Flags -To make following the wiki easier, each article that requires features is tagged appropriately. As soon as this feature isn't available in one of the games, the wiki will automatically show a warning indicating limited support. +To make following the Wiki easier, each article that requires features is tagged appropriately. As soon as this feature isn't available in one of the games, the Wiki will automatically show a warning indicating limited support. -This further supports the user when they select a game, as the wiki can automatically determine if an article is relevant or even possible in the selected game. +This further supports the user when they select a game, as the Wiki can automatically determine if an article is relevant or even possible in the selected game. ## Setting Feature Flags -Features required for an article are set in its [Meta Block](editing-articles#meta-block). If more than one feature is specified, the game needs to have all of them in order for the wiki to consider it supported. +Features required for an article are set in its [Meta Block](creating-editing-articles#meta-block). If more than one feature is specified, the game needs to have all of them in order for the Wiki to consider it supported. ```yaml features: - - USE_UGC + - USE_PANORAMA - USE_VSCRIPT ``` diff --git a/docs/contribute/basics/getting-started.md b/docs/contribute/basics/getting-started.md index 20be87f2..24517bec 100644 --- a/docs/contribute/basics/getting-started.md +++ b/docs/contribute/basics/getting-started.md @@ -5,7 +5,7 @@ weight: 0 # Getting Started -Welcome to the Strata Wiki! We appreciate your interest in contributing. +Welcome to the Strata Source Wiki! We appreciate your interest in contributing. This guide will teach you everything you need to know about writing articles. @@ -37,7 +37,7 @@ must adhere to these guidelines ## Setting Up The Wiki For Local Edits -In order to add/edit articles and test how they will appear in the Strata Wiki, the Wiki's documentation source repository should be locally cloned. +In order to add/edit articles and test how they will appear in the Strata Source Wiki, the Wiki's documentation source repository should be locally cloned. Before opening a pull request, it's suggested that you clone and build the wiki locally to ensure your changes work correctly. @@ -45,10 +45,12 @@ The source can be cloned from [StrataSource/Wiki](https://github.com/StrataSourc > [!WARNING] > Please make sure to not get mixed up with the [StrataSource/strata-wiki](https://github.com/StrataSource/strata-wiki) repository. -> This repository is not the documentation repository but instead the source code for the Strata Wiki itself. +> This repository is not the documentation repository but instead the source code for the Strata Source Wiki itself. > -> While this does get cloned with the documentation repository on first run, it should not need to be edited in order to add/edit articles to the wiki. +> While this does get cloned with the documentation repository on first run, it should not need to be edited in order to create/edit articles on the Wiki. If you are interested in working with the Wiki software, please read [Getting Started With The Wiki Software](../advanced/getting-started). -Please follow the README instructions in the `StrataSouce/Wiki` repository to finish setting up the Wiki once it has been cloned. +Please follow the README instructions in the `StrataSource/Wiki` repository to finish setting up the Wiki once it has been cloned. -After reading the guidelines and setting up the local instance of the Strata Wiki, continue to [editing articles](editing-articles). +## What's Next + +After reading the guidelines and setting up the local instance of the Strata Source Wiki, continue to [Creating & Editing Articles](creating-editing-articles). diff --git a/docs/contribute/basics/meta.json b/docs/contribute/basics/meta.json index e98357f9..3732cd1f 100644 --- a/docs/contribute/basics/meta.json +++ b/docs/contribute/basics/meta.json @@ -1,4 +1,4 @@ { "title": "Basics", - "weight": 20 + "weight": 0 } diff --git a/docs/contribute/basics/structure.md b/docs/contribute/basics/structure.md new file mode 100644 index 00000000..dbb8f5f9 --- /dev/null +++ b/docs/contribute/basics/structure.md @@ -0,0 +1,65 @@ +--- +title: Wiki Structure +weight: 20 +--- + +# Wiki Structure + +The wiki is structured on 3 levels: + +- Category +- Topic +- Article + +## Categories + +Categories group topics and articles together by a specific feature set, like "Panorama". + +Categories are located inside the [`docs` folder](https://github.com/StrataSource/Wiki/tree/main/docs) in the repo and all contain a `meta.json` file. This file includes all information needed about the category, like it's title: + +```json +{ + "title": "Contribute" +} +``` + +> [!NOTE] +> Adding a new category on the Wiki is not as simple as making the folder as it is controlled by the Wiki's software. If you wish to edit or create a new Wiki category please read the [Making Category](../advanced/creating-category) article. + +## Topics + +Topics, also knows as Subcategories, divide categories into different sections like `Overview`, `Controls` and `Reference`. + +Topics are folders inside categories and also have their own `meta.json` file: + +```json +{ + "title": "Basics", + "weight": 10 +} +``` + +The `weight` property is optional and tells the wiki how to sort the topics: Bigger weight means a topic will move further down. If no weight is specified, the wiki will default to infinite weight, making the topic appear at the bottom of the list. + +An additional property, `type`, is used to tell the Wiki software where certain game reference dumps should be generated and placed, like the classes, enums, and other types. These technically can be used for any topic, but they should only be used in the section the reference is associated with, the Panorama reference shouldn't go into the Material category. + +> [!NOTE] +> If `type` is anything other than `markdown`, which is also the default if it's not defined, then no other articles will appear in the topic. + +All currently available `type` properties: + +- `angelscript`: The AngelScript reference. +- `concommand`: All available ConCommands. Marked if they're Server/Client and/or Strata game specific. +- `convar`: All available ConVars. Marked if they're Server/Client and/or Strata game specific. +- `entity`: All entities in the engine. Marked if they're Strata game specific. +- `markdown`: The default, the topic will contain Markdown articles. +- `material`: All available material shaders for VMTs. +- `sound_operators`: All available sound operators for sound scripts. +- `typedoc`: The Panorama TypeDoc reference. +- `vscript`: The VScript Squirrel reference. + +## Articles + +Articles are the pages that make up the content of the wiki. Most articles are written by hand, but some are automatically generated from engine dumps and enhanced by manually written content. + +Articles that are fully manually written can be found as Markdown files inside topics. You can read about how these files are structured in [Creating & Editing Articles](../basics/creating-editing-articles). diff --git a/docs/contribute/elements/notices.md b/docs/contribute/elements/notices.md index 41a7bf0a..8012b0e8 100644 --- a/docs/contribute/elements/notices.md +++ b/docs/contribute/elements/notices.md @@ -59,10 +59,16 @@ Notices can be used to call out important or useful info. ```markdown > [!BUG] > This is a bug. +> It's really complicated. +> +> ### I _probably_ didn't cause [it](/) ``` > [!BUG] > This is a bug. +> It's really complicated. +> +> ### I _probably_ didn't cause [it](/) ## Portal 2: Community Edition Specific diff --git a/docs/contribute/imgs/home-page.png b/docs/contribute/imgs/home-page.png new file mode 100644 index 00000000..15828f68 Binary files /dev/null and b/docs/contribute/imgs/home-page.png differ diff --git a/docs/test/_meta.json b/docs/test/_meta.json index 0115a31e..0c4d1b59 100644 --- a/docs/test/_meta.json +++ b/docs/test/_meta.json @@ -1,3 +1,3 @@ { - "title": "Test suite" + "title": "Test Suite" } diff --git a/site b/site index aea981ee..4ef1e794 160000 --- a/site +++ b/site @@ -1 +1 @@ -Subproject commit aea981ee9c2c00cb348f58e9be965eb26955368e +Subproject commit 4ef1e7947eb20f23e3b5b6bf120e76960c4d4b82