Skip to content

Commit 04f42f3

Browse files
programmersd21programmersd21
committed
Initial commit: The Quickshell Book
0 parents  commit 04f42f3

277 files changed

Lines changed: 40529 additions & 0 deletions

File tree

Some content is hidden

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

‎.github/FUNDING.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
github: programmersd21

‎.github/workflows/build.yml‎

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

‎.github/workflows/validate.yml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
name: Validate
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
workflow_dispatch:
9+
10+
jobs:
11+
validate:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- uses: actions/checkout@v4
15+
- uses: actions/setup-node@v4
16+
with:
17+
node-version: '24'
18+
cache: 'npm'
19+
- run: npm ci
20+
- run: npm run build
21+
- run: npm run validate:links

‎.gitignore‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
node_modules
2+
docs/.vitepress/dist
3+
docs/.vitepress/cache
4+
*.log
5+
.DS_Store
6+
Thumbs.db
7+
*.swo
8+
*.swp
9+
*.swn
10+
.vscode
11+
.idea
12+
*.iml
13+
dist
14+
build
15+
.env
16+
.env.local
17+
*.tsbuildinfo

‎CONTRIBUTING.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Contributing
2+
3+
Contributions to The Quickshell Book are welcome. This document outlines the process.
4+
5+
## Types of Contributions
6+
7+
- **Content**: New chapters, sections, or improvements to existing content
8+
- **Corrections**: Fixes to technical inaccuracies, typos, or broken links
9+
- **Examples**: Runnable QML example code that accompanies chapters
10+
- **Translations**: Localization of the book into other languages
11+
12+
## Process
13+
14+
1. Open an issue describing your proposed change before starting work
15+
2. Fork the repository and create a branch for your changes
16+
3. Ensure content follows the book's existing style and structure
17+
4. Verify that all internal links are valid
18+
5. Submit a pull request with a clear description of the changes
19+
20+
## Guidelines
21+
22+
- Each pull request should address a single concern
23+
- Content should be accurate, concise, and free of marketing language
24+
- Code examples must be syntactically valid QML
25+
- New chapters require a `ChapterMeta` component and a `Recap` component
26+
- External sources should be cited in an HTML comment at the end of the file
27+
- Run `npm run build` and `npm run validate:links` before submitting
28+
29+
## Development Setup
30+
31+
```sh
32+
npm install
33+
npm run dev
34+
```
35+
36+
The book uses VitePress. Content is written in Markdown with Vue components for interactive elements. See the `docs/` directory structure for existing chapters.
37+
38+
## License
39+
40+
By contributing, you agree that your contributions will be licensed under the MIT License.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 The Quickshell Book Authors
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# The Quickshell Book
2+
3+
A comprehensive guide to building Wayland desktop shells with Quickshell and QML.
4+
5+
## Quick Start
6+
7+
```sh
8+
git clone https://github.com/programmersd21/the_quickshell_book.git
9+
cd the_quickshell_book
10+
npm install
11+
npm run dev
12+
```
13+
14+
Open `http://localhost:5173` in your browser.
15+
16+
## Examples
17+
18+
Each chapter comes with runnable QML examples in the [`examples/`](./examples) directory:
19+
20+
| Directory | Topic | Run With |
21+
|---|---|---|
22+
| `001-hello-world/` | First QML app | `qml6 hello.qml` |
23+
| `002-objects/` through `008-models-delegates/` | QML fundamentals | `qml6 *.qml` |
24+
| `009-calculator/` | Project: Calculator | `qml6 calculator.qml` |
25+
| `010-first-shell/` through `012-config-structure/` | Quickshell basics | `quickshell ./` |
26+
| `020-panel-window/` through `026-transparency-blur/` | Window types | `quickshell ./` |
27+
| `030-top-panel/` | Project: Top Panel | `quickshell ./` |
28+
| `040-widgets/` | Reusable widget components | Import into shell |
29+
| `090-app-launcher/` through `098-network-menu/` | App projects | `quickshell ./` |
30+
| `111-top-bar/` through `113-launcher/` | Shell components | `quickshell ./` |
31+
| `900-complete-shell/` | Complete desktop shell | `quickshell ./` |
32+
33+
## Prerequisites
34+
35+
- [Quickshell](https://quickshell.org/) (for most examples)
36+
- Qt6 (for `qml6` standalone examples)
37+
- Node.js >= 24.0.0 and npm (for the book site only)
38+
39+
## Development
40+
41+
```sh
42+
npm install
43+
npm run dev # dev server at http://localhost:5173
44+
npm run build # static output to docs/.vitepress/dist
45+
```
46+
47+
## Project Structure
48+
49+
```
50+
docs/ # Book content (Markdown)
51+
.vitepress/ # VitePress configuration and custom theme
52+
public/ # Static assets (images, favicon)
53+
examples/ # Runnable QML examples by chapter
54+
scripts/ # Utility scripts
55+
public/ # Source assets (favicon, banner)
56+
```
57+
58+
## License
59+
60+
MIT

0 commit comments

Comments
 (0)