Skip to content

Commit 67a7de8

Browse files
NonSwagNonSwag
authored
Merge pull request #102 from TheNextLvl-net/copilot/fix-101
Add comprehensive Copilot instructions for TheNextLvl documentation site
2 parents 26f9a55 + c77dfb5 commit 67a7de8

File tree

3 files changed

+176
-20
lines changed

3 files changed

+176
-20
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# TheNextLvl Documentation Website
2+
3+
TheNextLvl documentation is a Next.js 15 application built with Fumadocs, TypeScript, and Tailwind CSS. It serves as the documentation site for TheNextLvl Minecraft server community plugins and services, accessible at https://thenextlvl.net.
4+
5+
**ALWAYS reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**
6+
7+
## Working Effectively
8+
9+
### Bootstrap, Build, and Development
10+
11+
- **CRITICAL**: Some commands have network dependencies that may fail in restricted environments
12+
- Install dependencies:
13+
- Preferred: `bun install` -- takes ~1-24 seconds. NEVER CANCEL. Set timeout to 120+ seconds.
14+
- Fallback: `npm install` -- takes ~71 seconds. NEVER CANCEL. Set timeout to 180+ seconds.
15+
- Development server:
16+
- `bun run dev` or `npm run dev` -- starts in ~1 second, runs on http://localhost:3000
17+
- NEVER CANCEL: Development server runs indefinitely until stopped
18+
- Production build:
19+
- `bun run build` or `npm run build`
20+
- **WARNING**: Build fails in restricted network environments due to:
21+
1. Google Fonts (fonts.gstatic.com) access required for Inter font
22+
2. API calls to repo.thenextlvl.net for version information
23+
- Build takes ~20-30 seconds when network is available
24+
- If build fails with network errors, this is expected in sandboxed environments
25+
26+
### Package Manager Setup
27+
28+
- **Install Bun** (if not available):
29+
```bash
30+
curl -fsSL https://bun.sh/install | bash
31+
source ~/.bashrc
32+
bun --version
33+
```
34+
- The project specifies `[email protected]` as the package manager in package.json
35+
- Node.js fallback is supported for all commands
36+
37+
### Linting and Formatting
38+
39+
- **Format code**: `bun run format` or `npm run format` -- takes ~1 second. Uses Prettier.
40+
- **Lint code**: `bunx next lint` -- takes ~3 seconds. NEVER CANCEL. Set timeout to 30+ seconds.
41+
- Note: Shows warnings about TypeScript version mismatch (expected)
42+
- May show img element and unused variable warnings (expected)
43+
- **CRITICAL**: Always run formatting and linting before pushing changes or CI will fail
44+
45+
## Validation Scenarios
46+
47+
### Manual Testing Requirements
48+
49+
After making changes, ALWAYS perform these validation steps:
50+
51+
1. **Start development server**:
52+
- Run `bun run dev` or `npm run dev`
53+
- Verify server starts on http://localhost:3000 in ~1 second
54+
- Test homepage loads: `curl -s http://localhost:3000 | head -10`
55+
- Verify you see HTML content starting with `<!DOCTYPE html>`
56+
57+
2. **Test documentation pages**:
58+
- Navigate to http://localhost:3000/docs
59+
- **Note**: Pages may show 500 errors in restricted networks due to API calls - this is expected
60+
- In normal environments, verify navigation and content display works
61+
62+
3. **Validate formatting and linting**:
63+
- Run `bun run format` or `npm run format` - should complete in ~1 second without errors
64+
- Run `bunx next lint` - should complete in ~3 seconds with minimal warnings only
65+
- Expected warnings: img element usage, unused variables (these are normal)
66+
67+
## Key Architecture
68+
69+
### Directory Structure
70+
71+
```
72+
.
73+
├── README.md # Project overview and getting started
74+
├── package.json # Dependencies and scripts
75+
├── source.config.ts # Fumadocs MDX configuration
76+
├── next.config.mjs # Next.js configuration with redirects
77+
├── tsconfig.json # TypeScript configuration
78+
├── .eslintrc.json # ESLint configuration (legacy format)
79+
├── .prettierrc.json # Prettier configuration
80+
├── postcss.config.mjs # PostCSS with Tailwind
81+
├── content/ # Documentation content in MDX
82+
│ └── docs/ # Main docs content
83+
├── src/ # Application source code
84+
│ ├── app/ # Next.js App Router
85+
│ ├── lib/ # Utility libraries
86+
│ └── mdx-components.tsx # MDX component overrides
87+
├── public/ # Static assets
88+
└── .github/ # GitHub workflows and configuration
89+
└── workflows/build.yml # CI build workflow
90+
```
91+
92+
### Key Files to Know
93+
94+
- `src/lib/api.ts` - Contains API calls to repo.thenextlvl.net (causes network issues)
95+
- `src/app/layout.tsx` - Main app layout with Inter font from Google Fonts
96+
- `src/lib/source.ts` - Fumadocs content source configuration
97+
- `content/docs/` - All documentation content in MDX format
98+
- `.github/workflows/build.yml` - CI pipeline using Bun
99+
100+
### Content System
101+
102+
- Uses Fumadocs with MDX for documentation
103+
- Content lives in `content/docs/` directory
104+
- Each section has `meta.json` for navigation configuration
105+
- Some pages import `latestVersion` function from `src/lib/api.ts` for dynamic version display
106+
107+
## Common Tasks and Troubleshooting
108+
109+
### Network-Related Issues
110+
111+
- **Google Fonts errors**: Expected in restricted environments. Font loading fails but app still functions.
112+
- **repo.thenextlvl.net errors**: API calls for version information fail in restricted networks.
113+
- **Workaround**: For testing, temporarily comment out font imports and API calls if needed.
114+
115+
### Build Issues
116+
117+
- If build fails with "fetch failed" errors, this indicates network restrictions
118+
- Development mode (`bun run dev`) works even when build fails
119+
- Production build requires internet access for fonts and API calls
120+
121+
### Dependencies
122+
123+
- Always use `bun install` when possible (much faster than npm)
124+
- If Bun unavailable, `npm install` works as fallback
125+
- No test suite exists - validation is done through manual testing
126+
127+
### Making Content Changes
128+
129+
- Edit MDX files in `content/docs/` directory
130+
- Changes are hot-reloaded in development mode
131+
- Some content files use `await latestVersion()` calls that require network access
132+
- Always test documentation navigation after content changes
133+
134+
## CI/CD Integration
135+
136+
### GitHub Actions
137+
138+
- Workflow: `.github/workflows/build.yml`
139+
- Runs on: Ubuntu latest with Bun
140+
- Steps: checkout → setup bun → install dependencies → build
141+
- Environment variable: `NEXT_PUBLIC_BASE_URL: https://thenextlvl.net`
142+
- Build must pass for deployment
143+
144+
### Pre-commit Checklist
145+
146+
1. Run `bun run format` or `npm run format` - ensure all files formatted (~1 second)
147+
2. Run `bunx next lint` - check for linting issues (~3 seconds, warnings OK)
148+
3. Test development server starts: `bun run dev` or `npm run dev` (~1 second)
149+
4. Verify content changes display correctly at http://localhost:3000
150+
5. Test homepage accessibility: `curl -s http://localhost:3000 | head -10`
151+
6. Check that new files follow existing patterns
152+
153+
## Network Dependencies Summary
154+
155+
- **Google Fonts**: Inter font family (fonts.gstatic.com)
156+
- **Version API**: repo.thenextlvl.net for plugin version info
157+
- **Expected failures**: Both may fail in sandboxed/restricted environments
158+
- **Impact**: Development server works, but production build may fail

‎source.config.ts‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
import { defineConfig, defineDocs, frontmatterSchema, metaSchema } from "fumadocs-mdx/config";
2-
import { transformerCommandColor } from "./src/lib/command-transformer";
1+
import { defineConfig, defineDocs, frontmatterSchema, metaSchema } from "fumadocs-mdx/config"
2+
import { transformerCommandColor } from "./src/lib/command-transformer"
33

44
// You can customise Zod schemas for frontmatter and `meta.json` here
55
// see https://fumadocs.vercel.app/docs/mdx/collections#define-docs
@@ -10,7 +10,7 @@ export const docs = defineDocs({
1010
meta: {
1111
schema: metaSchema,
1212
},
13-
});
13+
})
1414

1515
export default defineConfig({
1616
mdxOptions: {
@@ -20,11 +20,9 @@ export default defineConfig({
2020
dark: "github-dark",
2121
},
2222
langAlias: {
23-
command: 'text',
23+
command: "text",
2424
},
25-
transformers: [
26-
transformerCommandColor(),
27-
],
25+
transformers: [transformerCommandColor()],
2826
},
2927
},
30-
});
28+
})

‎src/app/sitemap.ts‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,31 @@
1-
import type { MetadataRoute } from 'next';
2-
import { source } from '@/lib/source';
1+
import type { MetadataRoute } from "next"
2+
import { source } from "@/lib/source"
33

4-
export const revalidate = false;
4+
export const revalidate = false
55

66
export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
7-
const url = (path: string): string => new URL(path, process.env.NEXT_PUBLIC_BASE_URL).toString();
7+
const url = (path: string): string => new URL(path, process.env.NEXT_PUBLIC_BASE_URL).toString()
88

99
return [
1010
{
11-
url: url('/'),
12-
changeFrequency: 'monthly',
11+
url: url("/"),
12+
changeFrequency: "monthly",
1313
priority: 1,
1414
},
1515
{
16-
url: url('/docs'),
17-
changeFrequency: 'monthly',
16+
url: url("/docs"),
17+
changeFrequency: "monthly",
1818
priority: 0.8,
1919
},
2020
...(await Promise.all(
2121
source.getPages().map(async (page) => {
2222
return {
2323
url: url(page.url),
2424
lastModified: page.data.lastModified ? new Date(page.data.lastModified) : undefined,
25-
changeFrequency: 'weekly',
25+
changeFrequency: "weekly",
2626
priority: 0.5,
27-
} as MetadataRoute.Sitemap[number];
27+
} as MetadataRoute.Sitemap[number]
2828
}),
2929
)),
30-
];
31-
}
30+
]
31+
}

0 commit comments

Comments
 (0)