Skip to content

Commit 34a33c0

Browse files
skirtles-codeskirtles-code
committed
Add documentation
1 parent 37ea573 commit 34a33c0

File tree

10 files changed

+1783
-26
lines changed

10 files changed

+1783
-26
lines changed

‎.github/workflows/pages.yml

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Simple workflow for deploying static content to GitHub Pages
2+
name: Deploy to GitHub Pages
3+
4+
on:
5+
# Runs on pushes targeting the default branch
6+
push:
7+
branches: ['main']
8+
9+
# Allows you to run this workflow manually from the Actions tab
10+
workflow_dispatch:
11+
12+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
13+
permissions:
14+
contents: read
15+
pages: write
16+
id-token: write
17+
18+
# Allow only one concurrent deployment
19+
concurrency:
20+
group: 'pages'
21+
cancel-in-progress: false
22+
23+
jobs:
24+
# Single deploy job since we're just deploying
25+
deploy:
26+
environment:
27+
name: github-pages
28+
url: ${{ steps.deployment.outputs.page_url }}
29+
runs-on: ubuntu-latest
30+
steps:
31+
- name: Checkout
32+
uses: actions/checkout@v4
33+
- name: Install pnpm
34+
uses: pnpm/action-setup@v4
35+
with:
36+
version: 9
37+
- name: Set up Node
38+
uses: actions/setup-node@v4
39+
with:
40+
node-version: 20
41+
cache: 'pnpm'
42+
- name: Install dependencies
43+
run: pnpm install
44+
- name: Build
45+
run: pnpm run docs:build
46+
- name: Setup Pages
47+
uses: actions/configure-pages@v4
48+
- name: Upload artifact
49+
uses: actions/upload-pages-artifact@v3
50+
with:
51+
# Upload docs dist directory
52+
path: './docs/dist'
53+
- name: Deploy to GitHub Pages
54+
id: deployment
55+
uses: actions/deploy-pages@v4

‎docs/.vitepress/config.mts

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
import { resolve } from 'node:path'
2+
3+
import { defineConfigWithTheme } from 'vitepress'
4+
5+
export default defineConfigWithTheme({
6+
srcDir: './src',
7+
outDir: './dist',
8+
base: '/create-vue-lib/',
9+
title: '@skirtle/create-vue-lib',
10+
lang: 'en-US',
11+
description: 'Scaffolding tool for Vue libraries',
12+
cleanUrls: true,
13+
14+
sitemap: {
15+
hostname: 'https://skirtles-code.github.io/create-vue-lib/'
16+
},
17+
18+
transformHead({ page }) {
19+
if (page !== '404.md') {
20+
// The final replacement assumes `cleanUrls: true` is set
21+
const canonicalUrl = `https://skirtles-code.github.io/create-vue-lib/${page}`
22+
.replace(/index\.md$/, '')
23+
.replace(/\.md$/, '')
24+
25+
return [['link', { rel: 'canonical', href: canonicalUrl }]]
26+
}
27+
},
28+
29+
themeConfig: {
30+
search: {
31+
provider: 'local'
32+
},
33+
34+
nav: [
35+
{ text: 'Guide', link: '/introduction' }
36+
],
37+
38+
socialLinks: [
39+
{ icon: 'github', link: 'https://github.com/skirtles-code/create-vue-lib' }
40+
],
41+
42+
sidebar: [
43+
{
44+
text: 'Getting started',
45+
items: [
46+
{
47+
text: 'Introduction',
48+
link: '/introduction'
49+
}
50+
]
51+
}
52+
]
53+
}
54+
})

‎docs/.vitepress/theme/custom.css

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
:root {
2+
/* Switch the theme to green */
3+
--vp-c-brand-1: var(--vp-c-green-1);
4+
--vp-c-brand-2: var(--vp-c-green-2);
5+
--vp-c-brand-3: var(--vp-c-green-3);
6+
--vp-c-brand-soft: var(--vp-c-green-soft);
7+
8+
/* green-1 is too dark, so use green-2 instead */
9+
--vp-home-hero-name-color: var(--vp-c-brand-2);
10+
11+
/* Revert inline code to the old theme, so it doesn't look like a link */
12+
--vp-code-color: #476582;
13+
14+
/* Put borders on code and custom blocks */
15+
--custom-code-block-border: var(--vp-c-divider);
16+
17+
--vp-custom-block-danger-border: hsla(358, 75%, 44%, 0.4);
18+
--vp-custom-block-warning-border: hsla(32, 95%, 44%, 0.4);
19+
--vp-custom-block-tip-border: hsla(153, 25%, 44%, 0.4);
20+
--vp-custom-block-info-border: hsla(240, 10%, 64%, 0.4);
21+
}
22+
23+
/* Borders on custom blocks in dark mode */
24+
html:not(.dark) {
25+
--vp-custom-block-danger-bg: hsl(350, 81%, 96%);
26+
--vp-custom-block-warning-bg: hsl(45, 93%, 94%);
27+
--vp-custom-block-tip-bg: hsl(160, 81%, 98%);
28+
--vp-custom-block-info-bg: hsl(240, 6%, 97%);
29+
}
30+
31+
.dark {
32+
/* Inline code for the dark theme */
33+
--vp-code-color: #c9def1;
34+
}
35+
36+
/* Apply a border to code blocks and code groups */
37+
.vp-doc div[class*='language-'] {
38+
border: 1px solid var(--custom-code-block-border);
39+
}
40+
41+
.vp-code-group > .tabs {
42+
border: 1px solid var(--custom-code-block-border);
43+
border-bottom: 0 none;
44+
}
45+
46+
.vp-code-group > .blocks > div[class*='language-'] {
47+
border-top: 0 none;
48+
}
49+
50+
.vp-code-block-title-bar {
51+
border: 1px solid var(--custom-code-block-border);
52+
border-bottom: 0 none;
53+
box-shadow: none;
54+
}
55+
56+
/* Inline code in a custom block looks too much like a link */
57+
.custom-block.info code, .custom-block.tip code {
58+
color: var(--vp-code-color);
59+
}
60+
61+
.custom-block.info a > code, .custom-block.tip a > code {
62+
color: var(--vp-code-link-color);
63+
}
64+
65+
/* green-1 is much too close to black in the sidebar */
66+
html:not(.dark) .VPSidebar {
67+
--vp-c-brand-1: var(--vp-c-brand-3);
68+
}
69+
70+
/* Put arrows next to the sidebar items, otherwise the wrapping makes them difficult to read */
71+
.VPSidebarItem.level-1 .VPLink::before {
72+
border: 3px solid transparent;
73+
border-left: 4px solid var(--vp-c-text-2);
74+
border-right: none;
75+
content: "";
76+
left: -10px;
77+
position: absolute;
78+
top: 13px;
79+
}
80+
81+
.VPSidebarItem.level-1.is-active .VPLink::before {
82+
border-left-color: var(--vp-c-brand-1);
83+
}
84+
85+
/* Custom styling for quoting error messages and warnings. This might be better as a custom container, once they're supported */
86+
blockquote.quote-code-error {
87+
background-color: var(--vp-custom-block-warning-bg);
88+
border-color: var(--vp-custom-block-warning-border);
89+
font-family: var(--vp-font-family-mono);
90+
margin-left: 20px;
91+
margin-right: 20px;
92+
padding: 10px 10px 10px 20px;
93+
white-space: pre-wrap;
94+
}
95+
96+
.vp-doc blockquote.quote-code-error > p {
97+
font-size: 12.25px;
98+
}

‎docs/.vitepress/theme/index.ts

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
import DefaultTheme from 'vitepress/theme'
2+
import './custom.css'
3+
4+
export default DefaultTheme

‎docs/package.json

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
{
2+
"private": true,
3+
"scripts": {
4+
"clean": "rimraf dist .vitepress/cache",
5+
"dev": "vitepress dev .",
6+
"build": "vitepress build .",
7+
"preview": "vitepress preview ."
8+
},
9+
"dependencies": {
10+
"vue": "^3.5.13"
11+
},
12+
"devDependencies": {
13+
"@tsconfig/node22": "^22.0.0",
14+
"@types/node": "^22.13.0",
15+
"@vue/tsconfig": "^0.7.0",
16+
"npm-run-all2": "^7.0.2",
17+
"rimraf": "^6.0.1",
18+
"typescript": "~5.7.3",
19+
"vitepress": "^1.6.3",
20+
"vue-tsc": "^2.2.0"
21+
}
22+
}

‎docs/src/index.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<script setup>
2+
import { useRouter, withBase } from 'vitepress'
3+
import { onMounted } from 'vue'
4+
5+
const router = useRouter()
6+
7+
onMounted(() => {
8+
router.go(withBase('/introduction'))
9+
})
10+
</script>
11+
12+
Redirecting to the [Introduction](/introduction)...

‎docs/src/introduction.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Introduction
2+
3+
:::warning
4+
This tool is still work-in-progress.
5+
:::
6+
7+
`@skirtle/create-vue-lib` is a scaffolding tool for creating a Vite project to build a Vue-based library.
8+
9+
It currently requires `pnpm` to be used as the package manager.
10+
11+
## Usage
12+
13+
To create a new project:
14+
15+
```sh
16+
pnpm create @skirtle/vue-lib
17+
```
18+
19+
To get an extended list of customization questions:
20+
21+
```sh
22+
pnpm create @skirtle/vue-lib --extended
23+
```
24+
25+
To see the help message:
26+
27+
```sh
28+
pnpm create @skirtle/vue-lib --help
29+
```
30+
31+
## Features
32+
33+
As this is a scaffolding tool, you can (and should) edit the project configuration after it is created to do whatever else you need. The features here only outline what the tool can configure for you.
34+
35+
Currently, the following are used for all projects:
36+
37+
- `pnpm` as package manager
38+
- TypeScript
39+
- Project uses a `packages` directory, similar to Vue Core
40+
- Vite and Vitest
41+
- Vue
42+
43+
Optional features include:
44+
45+
- VitePress for documentation, with optional GitHub Pages deployment
46+
- A playground application to use for development
47+
- ESLint and ESLint Stylistic
48+
49+
The new project doesn't have any dependencies on special packages. It mostly uses the same dependencies as the official `create-vue` scaffolding tool, plus some widely used packages such as VitePress and ESLint Stylistic. In particular, there aren't any dependencies that tie you to the scaffolding tool.

‎package.json

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,8 @@
4545
"build:ts": "tsup src/index.ts --format cjs --target node18",
4646
"build:dts": "tsup src/index.ts --dts --format cjs --target node18",
4747
"start": "node ./dist/index.cjs",
48+
"docs:dev": "pnpm run --filter ./docs -r dev",
49+
"docs:build": "pnpm run --filter ./docs -r build",
4850
"preinstall": "npx only-allow pnpm"
4951
}
5052
}

0 commit comments

Comments
 (0)