From ebccec7bd5b813b3d5dd0489e61715d8e04795ef Mon Sep 17 00:00:00 2001 From: Prodigle Date: Mon, 12 Jan 2026 12:50:15 +0000 Subject: [PATCH 1/2] Add documentation for publishing modules to library search - Add publishing conventions to modules.md (tagging, structure, READMEs) - Add library search tutorial page with link to the search tool - Update tutorials index Co-Authored-By: Claude Opus 4.5 --- docs/documentation/modules.md | 57 +++++++++++++++++++++ docs/tutorials/index.md | 3 ++ docs/tutorials/library-search.md | 88 ++++++++++++++++++++++++++++++++ 3 files changed, 148 insertions(+) create mode 100644 docs/tutorials/library-search.md diff --git a/docs/documentation/modules.md b/docs/documentation/modules.md index e046d5e..4074cf9 100644 --- a/docs/documentation/modules.md +++ b/docs/documentation/modules.md @@ -134,3 +134,60 @@ The default gitignore may be a good start for what files you can safely leave ou ### Submodules TSWoW submodules have no relation to git submodules, but you can of course implement one using the other if you wish. + +## Publishing Modules + +If you want to share your module with others and make it discoverable, there are a few conventions to follow. + +### GitHub Topic + +Add the `tswow-module` topic to your GitHub repository. This is how the library search discovers modules: + +1. Go to your repository on GitHub +2. Click the gear icon next to "About" in the right sidebar +3. Add `tswow-module` to the Topics field +4. Save changes + +Your repository will be indexed within a few hours. + +### Repository Structure + +The library search supports two repository structures: + +#### Single Module Repository + +If your repository contains a single module, place the `datascripts/` or `livescripts/` folder at the repository root: + +``` +myname-mymodule/ +├── datascripts/ +├── livescripts/ +├── assets/ +└── README.md +``` + +#### Multi-Module Repository + +If your repository contains multiple modules, each top-level folder (that isn't an excluded name) is treated as a separate module: + +``` +module-library/ +├── myname-module-one/ +│ ├── datascripts/ +│ └── README.md +├── myname-module-two/ +│ ├── datascripts/ +│ └── README.md +└── README.md +``` + +**Note:** Certain common directory names are excluded from module detection: `.github`, `node_modules`, `docs`, `tests`, `src`, `lib`, `examples`, and similar development/tooling directories. + +### README Files + +Include README files to help users understand your modules: + +- **Repository README.md** - Explain the purpose of your repository, installation instructions, and an overview of what modules are included. +- **Per-module README.md** - For multi-module repositories, include a README.md in each module folder explaining what that specific module does. + +README content is indexed for search, so descriptive documentation helps users find your modules. diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index 01a421c..c2842ef 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -21,3 +21,6 @@ This sections contains user-submitted tutorials, walkthroughs or example modules - [**Client <-> Server Communications: Example Messaging**](./example-messaging) - _Demo showcasing how to utilize ClientExtensions dll._ + +- [**Library Search**](./library-search) + - _Find and share community-created TSWoW modules._ diff --git a/docs/tutorials/library-search.md b/docs/tutorials/library-search.md new file mode 100644 index 0000000..a5bc4e7 --- /dev/null +++ b/docs/tutorials/library-search.md @@ -0,0 +1,88 @@ +--- +layout: default +title: Library Search +nav_order: 5 +--- + +# TSWoW Library Search + +The TSWoW Library Search is a tool for discovering community-created modules and libraries. + +## [**Browse Libraries**](https://tswow-library-search.bold-term-1c95.workers.dev/) + +## Making Your Module Discoverable + +To have your module listed in the library search, you need to tag your GitHub repository and follow a few structural conventions. + +### GitHub Topic + +Add the `tswow-module` topic to your GitHub repository. This is how the library search discovers modules: + +1. Go to your repository on GitHub +2. Click the gear icon next to "About" in the right sidebar +3. Add `tswow-module` to the Topics field +4. Save changes + +Your repository will be indexed automatically within a few hours. + +### Repository Structure + +The library search supports two repository structures: + +#### Single Module Repository + +If your repository contains a single module, place the `datascripts/` or `livescripts/` folder at the repository root: + +``` +myname-mymodule/ +├── datascripts/ +├── livescripts/ +├── assets/ +└── README.md +``` + +#### Multi-Module Repository + +If your repository contains multiple modules, each top-level folder (that isn't an excluded name) is treated as a separate module: + +``` +module-library/ +├── myname-module-one/ +│ ├── datascripts/ +│ └── README.md +├── myname-module-two/ +│ ├── datascripts/ +│ └── README.md +└── README.md +``` + +**Note:** Certain common directory names are excluded from module detection: `.github`, `node_modules`, `docs`, `tests`, `src`, `lib`, `examples`, and similar development/tooling directories. + +### README Files + +Include README files to help users understand your modules: + +- **Repository README.md** - Explain the purpose of your repository, installation instructions, and an overview of what modules are included. +- **Per-module README.md** - For multi-module repositories, include a README.md in each module folder explaining what that specific module does. + +README content is indexed for search, so descriptive documentation helps users find your modules. + +## How Search Works + +The library search uses semantic vector indexing to help users find relevant modules. It understands the meaning behind your query. + +### What Gets Indexed + +The following content from your repository is indexed and used for search matching: + +- Repository name +- Repository description (from GitHub's "About" section) +- GitHub topics +- README content (first ~5,000 characters) + +### Tips for Better Discoverability + +- Write a clear, descriptive repository description in GitHub's "About" section +- Add relevant GitHub topics beyond just `tswow-module` (e.g., `custom-class`, `profession`, `dungeon`) +- Include keywords and use cases in your README that describe what your module does +- Use descriptive module folder names in multi-module repositories From 9e89915583996759c839ccca50e6fea2b7ca768b Mon Sep 17 00:00:00 2001 From: Prodigle Date: Mon, 19 Jan 2026 01:20:38 +0000 Subject: [PATCH 2/2] Move publishing docs to tutorial page and improve layout Removed the Publishing Modules section from the main modules documentation page and consolidated all content in the Library Search tutorial. Rewrote the tutorial page for better readability with clearer structure, numbered steps, and a table format. Co-Authored-By: Claude Opus 4.5 --- docs/documentation/modules.md | 59 +-------------------------- docs/tutorials/library-search.md | 68 +++++++++++++++----------------- 2 files changed, 33 insertions(+), 94 deletions(-) diff --git a/docs/documentation/modules.md b/docs/documentation/modules.md index 4074cf9..7ad3d31 100644 --- a/docs/documentation/modules.md +++ b/docs/documentation/modules.md @@ -133,61 +133,4 @@ The default gitignore may be a good start for what files you can safely leave ou ### Submodules -TSWoW submodules have no relation to git submodules, but you can of course implement one using the other if you wish. - -## Publishing Modules - -If you want to share your module with others and make it discoverable, there are a few conventions to follow. - -### GitHub Topic - -Add the `tswow-module` topic to your GitHub repository. This is how the library search discovers modules: - -1. Go to your repository on GitHub -2. Click the gear icon next to "About" in the right sidebar -3. Add `tswow-module` to the Topics field -4. Save changes - -Your repository will be indexed within a few hours. - -### Repository Structure - -The library search supports two repository structures: - -#### Single Module Repository - -If your repository contains a single module, place the `datascripts/` or `livescripts/` folder at the repository root: - -``` -myname-mymodule/ -├── datascripts/ -├── livescripts/ -├── assets/ -└── README.md -``` - -#### Multi-Module Repository - -If your repository contains multiple modules, each top-level folder (that isn't an excluded name) is treated as a separate module: - -``` -module-library/ -├── myname-module-one/ -│ ├── datascripts/ -│ └── README.md -├── myname-module-two/ -│ ├── datascripts/ -│ └── README.md -└── README.md -``` - -**Note:** Certain common directory names are excluded from module detection: `.github`, `node_modules`, `docs`, `tests`, `src`, `lib`, `examples`, and similar development/tooling directories. - -### README Files - -Include README files to help users understand your modules: - -- **Repository README.md** - Explain the purpose of your repository, installation instructions, and an overview of what modules are included. -- **Per-module README.md** - For multi-module repositories, include a README.md in each module folder explaining what that specific module does. - -README content is indexed for search, so descriptive documentation helps users find your modules. +TSWoW submodules have no relation to git submodules, but you can of course implement one using the other if you wish. \ No newline at end of file diff --git a/docs/tutorials/library-search.md b/docs/tutorials/library-search.md index a5bc4e7..ab91fe5 100644 --- a/docs/tutorials/library-search.md +++ b/docs/tutorials/library-search.md @@ -4,19 +4,21 @@ title: Library Search nav_order: 5 --- -# TSWoW Library Search +# Library Search -The TSWoW Library Search is a tool for discovering community-created modules and libraries. +Find and share community-created TSWoW modules. -## [**Browse Libraries**](https://tswow-library-search.bold-term-1c95.workers.dev/) +[**Browse the Library**](https://tswow-library-search.bold-term-1c95.workers.dev/){: .btn .btn-primary } -## Making Your Module Discoverable +--- + +## Publishing Your Module -To have your module listed in the library search, you need to tag your GitHub repository and follow a few structural conventions. +To make your module discoverable in the library search, follow these two steps: -### GitHub Topic +### 1. Add the GitHub Topic -Add the `tswow-module` topic to your GitHub repository. This is how the library search discovers modules: +The library search finds modules by looking for repositories tagged with `tswow-module`: 1. Go to your repository on GitHub 2. Click the gear icon next to "About" in the right sidebar @@ -25,13 +27,11 @@ Add the `tswow-module` topic to your GitHub repository. This is how the library Your repository will be indexed automatically within a few hours. -### Repository Structure - -The library search supports two repository structures: +### 2. Structure Your Repository -#### Single Module Repository +The search supports two layouts depending on whether you're publishing one module or several. -If your repository contains a single module, place the `datascripts/` or `livescripts/` folder at the repository root: +**Single module** — Place your endpoint folders at the repository root: ``` myname-mymodule/ @@ -41,48 +41,44 @@ myname-mymodule/ └── README.md ``` -#### Multi-Module Repository - -If your repository contains multiple modules, each top-level folder (that isn't an excluded name) is treated as a separate module: +**Multiple modules** — Each top-level folder becomes a separate module: ``` -module-library/ +my-module-collection/ ├── myname-module-one/ │ ├── datascripts/ │ └── README.md ├── myname-module-two/ -│ ├── datascripts/ +│ ├── livescripts/ │ └── README.md └── README.md ``` -**Note:** Certain common directory names are excluded from module detection: `.github`, `node_modules`, `docs`, `tests`, `src`, `lib`, `examples`, and similar development/tooling directories. +Common directories like `.github`, `node_modules`, `docs`, `tests`, `src`, `lib`, and `examples` are automatically excluded from module detection. -### README Files +--- -Include README files to help users understand your modules: +## Optimizing for Search -- **Repository README.md** - Explain the purpose of your repository, installation instructions, and an overview of what modules are included. -- **Per-module README.md** - For multi-module repositories, include a README.md in each module folder explaining what that specific module does. +The library uses semantic search, which means it understands the meaning behind queries rather than just matching keywords. -README content is indexed for search, so descriptive documentation helps users find your modules. +### Indexed Content -## How Search Works +The search indexes the following from your repository: -The library search uses semantic vector indexing to help users find relevant modules. It understands the meaning behind your query. +| Content | Notes | +|---------|-------| +| Repository name | Use a descriptive name | +| GitHub description | The "About" text on your repo | +| GitHub topics | All topics, not just `tswow-module` | +| README content | First ~5,000 characters | -### What Gets Indexed +### Tips for Discoverability -The following content from your repository is indexed and used for search matching: +**Write a strong GitHub description.** This appears prominently in search results. Be specific about what your module does. -- Repository name -- Repository description (from GitHub's "About" section) -- GitHub topics -- README content (first ~5,000 characters) +**Add relevant topics.** Go beyond `tswow-module` — add topics like `custom-class`, `profession`, `dungeon`, `quests`, or whatever describes your content. -### Tips for Better Discoverability +**Document your README well.** Explain what the module does, what features it includes, and how to use it. Good documentation helps both search ranking and users evaluating your module. -- Write a clear, descriptive repository description in GitHub's "About" section -- Add relevant GitHub topics beyond just `tswow-module` (e.g., `custom-class`, `profession`, `dungeon`) -- Include keywords and use cases in your README that describe what your module does -- Use descriptive module folder names in multi-module repositories +**Use descriptive folder names.** For multi-module repositories, clear folder names help users understand what each module contains at a glance.