Skip to content

Commit 5169bf3

Browse files
melvincarvalhomelvincarvalho
committed
Initial docs site with Docusaurus
0 parents  commit 5169bf3

43 files changed

Lines changed: 20278 additions & 0 deletions

Some content is hidden

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

‎.github/workflows/deploy.yml‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
name: Deploy to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: "pages"
15+
cancel-in-progress: true
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- uses: actions/checkout@v4
22+
- uses: actions/setup-node@v4
23+
with:
24+
node-version: 20
25+
cache: npm
26+
- run: npm ci
27+
- run: npm run build
28+
- uses: actions/upload-pages-artifact@v3
29+
with:
30+
path: build
31+
32+
deploy:
33+
environment:
34+
name: github-pages
35+
url: ${{ steps.deployment.outputs.page_url }}
36+
runs-on: ubuntu-latest
37+
needs: build
38+
steps:
39+
- uses: actions/deploy-pages@v4
40+
id: deployment

‎.gitignore‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎README.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# JSS Documentation
2+
3+
Documentation for [JavaScript Solid Server](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer).
4+
5+
Built with [Docusaurus](https://docusaurus.io/).
6+
7+
## Development
8+
9+
```bash
10+
npm install
11+
npm start
12+
```
13+
14+
## Build
15+
16+
```bash
17+
npm run build
18+
```
19+
20+
## Deploy
21+
22+
Automatically deploys to GitHub Pages on push to `main` via GitHub Actions.
23+
24+
Live at: https://javascriptsolidserver.github.io/docs/

‎docs/core-concepts/content-negotiation.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
sidebar_position: 3
3+
title: Content Negotiation
4+
description: How JSS handles different RDF formats
5+
---
6+
7+
# Content Negotiation
8+
9+
Content negotiation allows clients to request data in different formats.
10+
11+
## Supported Formats
12+
13+
| Format | Content-Type | Default |
14+
|--------|--------------|---------|
15+
| JSON-LD | `application/ld+json` | Yes |
16+
| Turtle | `text/turtle` | With `--conneg` |
17+
| HTML | `text/html` | For profiles |
18+
19+
## Requesting formats
20+
21+
Use the `Accept` header:
22+
23+
```bash
24+
# Get JSON-LD (default)
25+
curl http://localhost:3000/alice/public/data
26+
27+
# Get Turtle (requires --conneg)
28+
curl -H "Accept: text/turtle" http://localhost:3000/alice/public/data
29+
30+
# Get HTML (for browsing)
31+
curl -H "Accept: text/html" http://localhost:3000/alice/public/data
32+
```
33+
34+
## Enable Turtle support
35+
36+
```bash
37+
jss start --conneg
38+
```
39+
40+
Or via environment variable:
41+
42+
```bash
43+
JSS_CONNEG=true jss start
44+
```

‎docs/core-concepts/json-ld-first.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
sidebar_position: 1
3+
title: JSON-LD First
4+
description: Why JSS treats JSON-LD as the native format
5+
---
6+
7+
# JSON-LD First
8+
9+
JSS is a **JSON-LD native implementation**. Unlike traditional Solid servers that treat Turtle as the primary format, JSS:
10+
11+
- **Stores everything as JSON-LD** - No RDF parsing overhead
12+
- **Serves JSON-LD by default** - Web apps consume responses directly
13+
- **Content negotiation is optional** - Enable Turtle with `--conneg` when needed
14+
15+
## Why JSON-LD?
16+
17+
1. **Performance** - JSON parsing is native to JavaScript
18+
2. **Simplicity** - JSON-LD is valid JSON, works with any tooling
19+
3. **Web-native** - Browsers understand JSON natively
20+
4. **Semantic web ready** - JSON-LD is a W3C standard RDF serialization
21+
22+
## When to enable content negotiation
23+
24+
Enable `--conneg` when:
25+
- Interoperating with Turtle-based Solid apps
26+
- Serving data to legacy Solid clients
27+
- Running conformance tests
28+
29+
```bash
30+
# JSON-LD only (fast, default)
31+
jss start
32+
33+
# With Turtle support
34+
jss start --conneg
35+
```

‎docs/core-concepts/pods-and-resources.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
sidebar_position: 2
3+
title: Pods and Resources
4+
description: Understanding Solid's data model
5+
---
6+
7+
# Pods and Resources
8+
9+
## What is a Pod?
10+
11+
A pod (Personal Online Data Store) is a user's data container. Each user gets their own pod with:
12+
13+
- A WebID profile (`/alice/#me`)
14+
- Public and private containers
15+
- Access control via ACL files
16+
17+
## Pod Structure
18+
19+
```
20+
/alice/
21+
├── index.html # WebID profile (HTML with JSON-LD)
22+
├── .acl # Root ACL
23+
├── inbox/ # Notifications (public append)
24+
├── public/ # Public files
25+
├── private/ # Private files (owner only)
26+
└── settings/ # User preferences
27+
├── prefs
28+
├── publicTypeIndex
29+
└── privateTypeIndex
30+
```
31+
32+
## Resources
33+
34+
Resources are files within a pod. They can be:
35+
36+
- **RDF resources** - JSON-LD or Turtle documents
37+
- **Non-RDF resources** - Images, PDFs, any file type
38+
39+
## Containers
40+
41+
Containers are directories that can contain resources and other containers. They're represented as LDP Basic Containers.

‎docs/features/access-control.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
sidebar_position: 4
3+
title: Access Control (WAC)
4+
description: Web Access Control with .acl files
5+
---
6+
7+
# Access Control
8+
9+
JSS uses Web Access Control (WAC) for authorization via `.acl` files.
10+
11+
## How it works
12+
13+
Each resource or container can have an `.acl` file that defines who can access it and how.
14+
15+
## ACL Structure
16+
17+
```turtle
18+
@prefix acl: <http://www.w3.org/ns/auth/acl#>.
19+
@prefix foaf: <http://xmlns.com/foaf/0.1/>.
20+
21+
# Owner has full access
22+
<#owner>
23+
a acl:Authorization;
24+
acl:agent <http://localhost:3000/alice/#me>;
25+
acl:accessTo <./>;
26+
acl:default <./>;
27+
acl:mode acl:Read, acl:Write, acl:Control.
28+
29+
# Public can read
30+
<#public>
31+
a acl:Authorization;
32+
acl:agentClass foaf:Agent;
33+
acl:accessTo <./>;
34+
acl:default <./>;
35+
acl:mode acl:Read.
36+
```
37+
38+
## Access Modes
39+
40+
| Mode | Permission |
41+
|------|------------|
42+
| `acl:Read` | Read resources |
43+
| `acl:Write` | Create, update, delete |
44+
| `acl:Append` | Add to container only |
45+
| `acl:Control` | Modify ACL files |
46+
47+
## Agent Types
48+
49+
- `acl:agent` - Specific WebID
50+
- `acl:agentClass foaf:Agent` - Anyone (public)
51+
- `acl:agentClass acl:AuthenticatedAgent` - Any authenticated user

‎docs/features/authentication.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
sidebar_position: 5
3+
title: Authentication
4+
description: Solid-OIDC, Nostr NIP-98, and token authentication
5+
---
6+
7+
# Authentication
8+
9+
JSS supports multiple authentication methods.
10+
11+
## Simple Tokens (Development)
12+
13+
Token returned from pod creation:
14+
15+
```bash
16+
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:3000/alice/private/
17+
```
18+
19+
## Solid-OIDC
20+
21+
### Built-in Identity Provider
22+
23+
```bash
24+
jss start --idp
25+
```
26+
27+
Create a user:
28+
```bash
29+
curl -X POST http://localhost:3000/.pods \
30+
-H "Content-Type: application/json" \
31+
-d '{"name": "alice", "email": "alice@example.com", "password": "secret123"}'
32+
```
33+
34+
OIDC Discovery: `/.well-known/openid-configuration`
35+
36+
### External Identity Providers
37+
38+
JSS accepts DPoP-bound tokens from any Solid IdP:
39+
40+
```bash
41+
curl -H "Authorization: DPoP ACCESS_TOKEN" \
42+
-H "DPoP: DPOP_PROOF" \
43+
http://localhost:3000/alice/private/
44+
```
45+
46+
## Nostr Authentication (NIP-98)
47+
48+
Sign requests with Nostr keys. Install the credential helper for git:
49+
50+
```bash
51+
npm install -g git-credential-nostr
52+
git-credential-nostr generate
53+
git config --global credential.helper nostr
54+
git config --global nostr.privkey <key>
55+
```
56+
57+
See [git-credential-nostr](https://github.com/JavaScriptSolidServer/git-credential-nostr) for details.

‎docs/features/git-integration.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
sidebar_position: 6
3+
title: Git Integration
4+
description: Clone and push to pods via git protocol
5+
---
6+
7+
# Git Integration
8+
9+
JSS includes a Git HTTP backend, allowing you to use standard git commands with pods.
10+
11+
## Enable Git support
12+
13+
```bash
14+
jss start --git
15+
```
16+
17+
## Clone a repository
18+
19+
```bash
20+
git clone http://localhost:3000/alice/myrepo
21+
```
22+
23+
Requires `acl:Read` permission.
24+
25+
## Push changes
26+
27+
```bash
28+
cd myrepo
29+
echo "Update" >> README.md
30+
git add . && git commit -m "Update"
31+
git push
32+
```
33+
34+
Requires `acl:Write` permission.
35+
36+
## Auto-checkout
37+
38+
After a successful push to a non-bare repository, JSS automatically updates the working directory. No post-receive hooks needed.
39+
40+
## Git with Nostr Authentication
41+
42+
Use [git-credential-nostr](https://github.com/JavaScriptSolidServer/git-credential-nostr) for push authentication:
43+
44+
```bash
45+
npm install -g git-credential-nostr
46+
git-credential-nostr generate
47+
git config --global credential.helper nostr
48+
git config --global nostr.privkey <key>
49+
50+
# Generate ACL for your repo
51+
cd myrepo
52+
git-credential-nostr acl > .acl
53+
git add .acl && git commit -m "Add ACL"
54+
git push
55+
```
56+
57+
See [Git Push with Nostr](/guides/git-push-nostr) for a complete guide.

0 commit comments

Comments
 (0)