Skip to content

Vue #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
HarryCordewener merged 4 commits into from
Oct 21, 2025
Merged

Vue #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2465288
WIP
HarryCordewener Oct 21, 2025
b7c643e
WIP3
HarryCordewener Oct 21, 2025
cad54b6
WIP4
HarryCordewener Oct 21, 2025
d06cfe2
Don't need this. Do need that.
HarryCordewener Oct 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/CODEOWNERS
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
@HarryCordewener
@SharpMUSH
3 changes: 3 additions & 0 deletions .gitmodules
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
[submodule "SharpMUSH-submodule"]
path = SharpMUSH-submodule
url = https://github.com/SharpMUSH/SharpMUSH.git
45 changes: 28 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,44 @@
# Starlight Starter Kit: Basics
# SharpMUSH Documentation

The official documentation website for SharpMUSH, built with [Astro](https://astro.build) and [Starlight](https://starlight.astro.build).

[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)

```
npm create astro@latest -- --template starlight
```
## 🎯 Overview

[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics)
[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/starlight/tree/main/examples/basics)
[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/withastro/starlight&create_from_path=examples/basics)
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fwithastro%2Fstarlight%2Ftree%2Fmain%2Fexamples%2Fbasics&project-name=my-starlight-docs&repository-name=my-starlight-docs)
This documentation site automatically pulls help files from the main [SharpMUSH repository](https://github.com/SharpMUSH/SharpMUSH) using Git submodules and converts them to a modern, searchable web interface.

> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
## 🚀 Quick Start

## 🚀 Project Structure
```bash
# Clone with submodules
git clone --recursive https://github.com/SharpMUSH/SharpMUSH.Docs.git
cd SharpMUSH.Docs

# Install dependencies
npm install

# Start development server (auto-converts docs)
npm run dev
```

Inside of your Astro + Starlight project, you'll see the following folders and files:
## � Project Structure

```
.
├── public/
├── SharpMUSH-submodule/ # Git submodule to main repository
├── scripts/
│ ├── convert-docs.js # Documentation converter
│ └── README.md # Converter documentation
├── src/
│ ├── assets/
│ ├── content/
│ │ ├── docs/
│ └── content.config.ts
│ │ └── docs/
│ │ └── reference/
│ │ └── sharpmush-help/ # Auto-generated from submodule
│ └── assets/
├── .github/workflows/ # CI/CD for automatic updates
├── astro.config.mjs
├── package.json
└── tsconfig.json
└── package.json
```

Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
Expand Down
1 change: 1 addition & 0 deletions SharpMUSH-submodule
Open in desktop
Submodule SharpMUSH-submodule added at 1e64a1
1 change: 1 addition & 0 deletions astro.config.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import netlify from '@astrojs/netlify';

// https://astro.build/config
export default defineConfig({
site: 'https://sharpmush.com',
integrations: [
starlight({
title: 'SharpMUSH',
Expand Down
13 changes: 9 additions & 4 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,16 @@
"type": "module",
"version": "0.0.1",
"scripts": {
"dev": "astro dev",
"start": "astro dev",
"build": "astro build",
"dev": "npm run convert-docs && astro dev",
"start": "npm run convert-docs && astro dev",
"build": "npm run convert-docs && astro build",
"preview": "astro preview",
"astro": "astro"
"astro": "astro",
"convert-docs": "node scripts/convert-docs.js",
"index-headers": "node scripts/index-headers.js",
"update-submodule": "git submodule update --remote",
"prebuild": "npm run update-submodule && npm run index-headers && npm run convert-docs",
"predev": "npm run convert-docs"
},
"dependencies": {
"@astrojs/netlify": "^6.2.4",
Expand Down
173 changes: 173 additions & 0 deletions scripts/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,173 @@
# Documentation Conversion Scripts

This directory contains scripts for automatically converting SharpMUSH documentation from the Git submodule into Starlight-compatible format.

## Files

### `convert-docs.js`

Converts markdown files from the SharpMUSH submodule into Starlight-compatible documentation with:

- **Filename-based titles**: Uses predefined titles based on filenames for consistent documentation structure
- **Frontmatter generation**: Adds Starlight-compatible YAML frontmatter with title and description
- **Heading level adjustment**: Converts H1 (`#`) to H2 (`##`) and H2 (`##`) to H3 (`###`) for better integration with Starlight navigation
- **Link conversion**: Converts PennMUSH-style internal links (`[help TOPIC|DISPLAY]`) to Starlight navigation links
- **Automatic categorization**: Intelligently maps help topics to appropriate documentation files

### `index-headers.js`

Analyzes all documentation files to generate comprehensive header mappings:

- **Header extraction**: Finds all `#` and `##` headers in documentation files
- **Normalization**: Converts headers to consistent format for matching
- **Mapping generation**: Creates topic-to-document mappings for accurate cross-references
- **JSON output**: Saves mappings to `doc-mappings.json` for use by the converter
- **Analysis reporting**: Provides statistics on headers found per document

#### Link Conversion Examples

- `[help ATTRIBUTE FLAGS|attribute flags]` → `[attribute flags](/reference/sharpmush-help/pennattr/#attribute-flags)`
- `[help @set|@set]` → `[@set](/reference/sharpmush-help/penncmd/#set)`
- `[help nearby()|nearby()]` → `[nearby()](/reference/sharpmush-help/pennfunc/#nearby)`
- `[attribute flags2]` → `[attribute flags2](/reference/sharpmush-help/pennattr/#attribute-flags2)`
- `[nearby()]` → `[nearby()](/reference/sharpmush-help/pennfunc/#nearby)`

### Exclusions

The converter intelligently excludes certain patterns from conversion:

- **Code blocks**: Content inside ``` fenced blocks and `backticks` is preserved
- **Function calls**: `[get(obj/attr)]`, `[function(arg1,arg2)]` are not converted
- **Paths and URLs**: Links containing `/`, `#`, `$`, `&` are skipped
- **Short patterns**: Single characters or very short strings (unless starting with @ or &)
- **Numbers**: Pure numeric content like `[123]` is ignored
- **Existing markdown**: Already converted links with `](` are skipped

#### Document Mapping

The script automatically categorizes topics into appropriate documents:

- **pennattr**: Attribute-related topics (ATTRIBUTE FLAGS, ATTRIBUTE TREES, etc.)
- **penncmd**: Commands (topics starting with @)
- **pennfunc**: Functions (topics ending with ())
- **pennflag**: Flag-related topics
- **pennlock**: Lock-related topics
- **pennmail**: Mail system topics
- **pennchat**: Chat/channel topics
- **pennevents**: Event system topics
- **pennhttp**: HTTP-related topics
- **pennpueb**: Pueblo client topics
- **pennconf**: Configuration and other topics (fallback)

#### File Titles

Document titles are mapped from filenames for consistency:

| Filename | Title |
|----------|-------|
| `pennattr.md` | Attributes |
| `pennchat.md` | Chat and Channels |
| `penncmd.md` | Commands |
| `penncode.md` | Coding and Programming |
| `pennconf.md` | Configuration |
| `pennevents.md` | Events |
| `pennflag.md` | Flags |
| `pennfunc.md` | Functions |
| `pennhttp.md` | HTTP Features |
| `pennlock.md` | Locks |
| `pennmail.md` | Mail System |
| `pennpueb.md` | Pueblo Client |
| `penntop.md` | Top-Level Topics |

## Usage

### Manual Conversion

```bash
npm run convert-docs
```

### Generate Header Mappings

```bash
npm run index-headers
```

### Update Submodule and Convert

```bash
npm run update-submodule
npm run index-headers
npm run convert-docs
```

### Automatic Conversion

The conversion runs automatically during:

- `npm run dev` (development server)
- `npm run build` (production build)
- `npm run start` (development server)

## Configuration

To modify the conversion behavior, edit the following sections in `convert-docs.js`:

- **FILE_TITLES**: Update filename-to-title mappings for consistent documentation structure
- **doc-mappings.json**: Generated header-to-document mappings (regenerate with `npm run index-headers`)
- **convertInternalLinks()**: Modify link conversion patterns
- **addFrontmatter()**: Customize frontmatter generation

### Updating Header Mappings

Header mappings are automatically generated from the source documentation:

```bash
# Regenerate mappings from current documentation
npm run index-headers
```

This creates/updates `scripts/doc-mappings.json` with:
- All headers found in documentation files
- Normalized header names for consistent matching
- Document assignments for each header
- Metadata about the generation process

### Updating File Titles

To change the title for a documentation file, update the `FILE_TITLES` object:

```javascript
const FILE_TITLES = {
'pennattr.md': 'New Attributes Title',
'penncmd.md': 'New Commands Title',
// ...
};
```

## Troubleshooting

### Submodule Not Found

If you get an error about the source directory not being found:

```bash
git submodule init
git submodule update
```

### Link Conversion Issues

If internal links aren't converting properly:

1. Check the topic name in the source markdown
2. Verify the mapping in `DOC_MAPPINGS`
3. Ensure the target document exists in the output directory

### Build Failures

If the build fails during conversion:

1. Ensure Node.js version 16+ is installed
2. Check that all source files are valid markdown
3. Verify file permissions in the output directory
Loading