Skip to content

Commit d8bc3d0

Browse files
iamaanahmadiamaanahmad
authored
Merge pull request #1 from iamaanahmad/main
improve docs UX, SEO metadata, and pages deployment
2 parents 631a240 + 6ce365a commit d8bc3d0

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

74 files changed

+22364
-21630
lines changed

‎.github/workflows/deploy.yml‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
name: Deploy to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
concurrency:
15+
group: pages
16+
cancel-in-progress: true
17+
18+
jobs:
19+
build:
20+
runs-on: ubuntu-latest
21+
timeout-minutes: 20
22+
23+
steps:
24+
- name: Checkout
25+
uses: actions/checkout@v4
26+
27+
- name: Setup Pages
28+
uses: actions/configure-pages@v5
29+
30+
- name: Setup Node.js
31+
uses: actions/setup-node@v4
32+
with:
33+
node-version: '20'
34+
cache: npm
35+
36+
- name: Install dependencies
37+
run: npm ci
38+
39+
- name: Build static site
40+
run: npm run deploy
41+
env:
42+
NEXT_PUBLIC_BASE_PATH: ${{ github.event.repository.name != format('{0}.github.io', github.repository_owner) && format('/{0}', github.event.repository.name) || '' }}
43+
44+
- name: Validate static output
45+
run: |
46+
test -d out
47+
test -f out/index.html
48+
49+
- name: Upload Pages artifact
50+
uses: actions/upload-pages-artifact@v3
51+
with:
52+
path: ./out
53+
54+
deploy:
55+
needs: build
56+
runs-on: ubuntu-latest
57+
timeout-minutes: 10
58+
environment:
59+
name: github-pages
60+
url: ${{ steps.deployment.outputs.page_url }}
61+
62+
steps:
63+
- name: Deploy to GitHub Pages
64+
id: deployment
65+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 44 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,45 @@
1-
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
2-
3-
# dependencies
4-
/node_modules
5-
/.pnp
6-
.pnp.*
7-
.yarn/*
8-
!.yarn/patches
9-
!.yarn/plugins
10-
!.yarn/releases
11-
!.yarn/versions
12-
13-
# testing
14-
/coverage
15-
16-
# next.js
17-
/.next/
18-
/out/
19-
20-
# production
21-
/build
22-
23-
# misc
24-
.DS_Store
25-
*.pem
26-
27-
# debug
28-
npm-debug.log*
29-
yarn-debug.log*
30-
yarn-error.log*
31-
.pnpm-debug.log*
32-
33-
# vercel
34-
.vercel
35-
36-
# typescript
37-
*.tsbuildinfo
38-
next-env.d.ts
39-
40-
.genkit/*
41-
.env*
42-
43-
# firebase
44-
firebase-debug.log
1+
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
2+
3+
# dependencies
4+
/node_modules
5+
/.pnp
6+
.pnp.*
7+
.yarn/*
8+
!.yarn/patches
9+
!.yarn/plugins
10+
!.yarn/releases
11+
!.yarn/versions
12+
13+
# testing
14+
/coverage
15+
16+
# next.js
17+
/.next/
18+
/out/
19+
20+
# production
21+
/build
22+
23+
# misc
24+
.DS_Store
25+
*.pem
26+
27+
# debug
28+
npm-debug.log*
29+
yarn-debug.log*
30+
yarn-error.log*
31+
.pnpm-debug.log*
32+
33+
# vercel
34+
.vercel
35+
36+
# typescript
37+
*.tsbuildinfo
38+
next-env.d.ts
39+
40+
.genkit/*
41+
.env*
42+
43+
# firebase
44+
firebase-debug.log
4545
firestore-debug.log

‎.idx/dev.nix‎

Lines changed: 0 additions & 44 deletions
This file was deleted.

‎.idx/icon.png‎

-31.4 KB
Binary file not shown.

‎README.md‎

Lines changed: 105 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,107 @@
1-
# Firebase Studio
1+
# APIDocumer
22

3-
This is a NextJS starter in Firebase Studio.
3+
APIDocumer is a Next.js-based OpenAPI documentation viewer for static hosting. It loads `public/openapi.yaml`, groups endpoints by tags, and renders endpoint details, schemas, and examples in a searchable UI.
44

5-
To get started, take a look at src/app/page.tsx.
5+
## Features
6+
7+
- OpenAPI 3.x viewer with sidebar navigation by tags
8+
- Full-width, responsive documentation layout
9+
- Endpoint search (path, method, summary, description, tag)
10+
- Request/response schema and example rendering
11+
- SEO-aware metadata generated from OpenAPI spec fields
12+
- Static export support for GitHub Pages
13+
14+
## Tech Stack
15+
16+
- Next.js 15
17+
- React 19
18+
- TypeScript
19+
- Tailwind CSS + Radix UI
20+
21+
## Project Structure
22+
23+
- `src/app/page.tsx`: server entry, OpenAPI loader, and SEO metadata generation
24+
- `src/components/doc-viewer.tsx`: main documentation UI
25+
- `src/components/endpoint-display.tsx`: endpoint details renderer
26+
- `src/lib/openapi-parser.ts`: tag grouping and `$ref` helpers
27+
- `public/openapi.yaml`: source OpenAPI spec loaded at build/runtime
28+
- `.github/workflows/deploy.yml`: GitHub Pages deployment workflow
29+
30+
## Local Development
31+
32+
1. Install dependencies:
33+
34+
```bash
35+
npm ci
36+
```
37+
38+
2. Run dev server:
39+
40+
```bash
41+
npm run dev
42+
```
43+
44+
3. Open `http://localhost:9002`.
45+
46+
## Build and Export
47+
48+
Generate production static output:
49+
50+
```bash
51+
npm run deploy
52+
```
53+
54+
This runs `next build` (with `output: 'export'`) and creates `out/` with `.nojekyll` for GitHub Pages compatibility.
55+
56+
## Deployment (GitHub Pages)
57+
58+
This repository includes `.github/workflows/deploy.yml` which:
59+
60+
- installs dependencies with `npm ci`
61+
- builds static output via `npm run deploy`
62+
- uploads `out/` as the Pages artifact
63+
- deploys to GitHub Pages
64+
65+
### Required Repository Settings
66+
67+
1. In GitHub, go to **Settings > Pages**.
68+
2. Set source to **GitHub Actions**.
69+
3. Ensure the default branch for deployment is `main`.
70+
71+
## OpenAPI Source
72+
73+
APIDocumer reads documentation data from `public/openapi.yaml`.
74+
75+
For best SEO and discoverability, include high-quality fields in your spec:
76+
77+
- `info.title`
78+
- `info.description`
79+
- `info.version`
80+
- `servers[0].url`
81+
- optional `info.x-keywords` (string array)
82+
83+
These are used to build page metadata (title, description, keywords, Open Graph, and Twitter cards).
84+
85+
## Contributing
86+
87+
1. Fork the repository
88+
2. Create a feature branch
89+
3. Make changes with clear commit messages
90+
4. Open a pull request with:
91+
- what changed
92+
- why it changed
93+
- screenshots for UI changes
94+
95+
## Quality Checks
96+
97+
Use these before opening a PR:
98+
99+
```bash
100+
npm run typecheck
101+
npm run lint
102+
npm run build
103+
```
104+
105+
## License
106+
107+
Add your preferred open-source license file (for example `MIT`) and update this section accordingly.

‎apphosting.yaml‎

Lines changed: 0 additions & 7 deletions
This file was deleted.

‎components.json‎

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,21 @@
1-
{
2-
"$schema": "https://ui.shadcn.com/schema.json",
3-
"style": "default",
4-
"rsc": true,
5-
"tsx": true,
6-
"tailwind": {
7-
"config": "tailwind.config.ts",
8-
"css": "src/app/globals.css",
9-
"baseColor": "neutral",
10-
"cssVariables": true,
11-
"prefix": ""
12-
},
13-
"aliases": {
14-
"components": "@/components",
15-
"utils": "@/lib/utils",
16-
"ui": "@/components/ui",
17-
"lib": "@/lib",
18-
"hooks": "@/hooks"
19-
},
20-
"iconLibrary": "lucide"
1+
{
2+
"$schema": "https://ui.shadcn.com/schema.json",
3+
"style": "default",
4+
"rsc": true,
5+
"tsx": true,
6+
"tailwind": {
7+
"config": "tailwind.config.ts",
8+
"css": "src/app/globals.css",
9+
"baseColor": "neutral",
10+
"cssVariables": true,
11+
"prefix": ""
12+
},
13+
"aliases": {
14+
"components": "@/components",
15+
"utils": "@/lib/utils",
16+
"ui": "@/components/ui",
17+
"lib": "@/lib",
18+
"hooks": "@/hooks"
19+
},
20+
"iconLibrary": "lucide"
2121
}

‎docs/blueprint.md‎

Lines changed: 0 additions & 19 deletions
This file was deleted.

0 commit comments

Comments
 (0)