Skip to content

Commit cf9bd1f

Browse files
fratzingerfratzinger
committed
docs: refactor docs
1 parent 3ec1ba5 commit cf9bd1f

File tree

141 files changed

+11154
-3097
lines changed

Some content is hidden

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

141 files changed

+11154
-3097
lines changed

‎README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,8 @@
2727
- added throwIf
2828
- added throwIfIsProvider
2929
- added throwIfIsMulti
30-
- added paramsForServer2 & paramsForClient2
30+
31+
- removed old paramsForServer & changed to hook
3132

3233
- added 'onDelete' & 'createRelated'
3334

‎docs/.vitepress/config.mts‎

Lines changed: 79 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,19 @@
11
import { defineConfig } from 'vitepress'
2-
import { name, description, ogUrl, ogImage } from './meta'
2+
import { name, description, ogUrl, ogImage, repository, mainBranch } from './meta'
33
import { version } from '../../package.json'
4+
import { resolve } from 'node:path'
5+
import { fileURLToPath } from 'node:url'
6+
import { discoverUtilities } from './utilities'
7+
import { MarkdownTransform } from './plugins/markdownTransform'
8+
import { transformerTwoslash } from '@shikijs/vitepress-twoslash'
9+
import tailwindcss from '@tailwindcss/vite'
10+
11+
const __dirname = fileURLToPath(new URL('.', import.meta.url))
12+
13+
const utilities = await discoverUtilities()
414

515
export default defineConfig({
6-
title: 'feathers-hooks-common/index.js',
16+
title: name,
717
lastUpdated: true,
818
description: '',
919
head: [
@@ -19,24 +29,19 @@ export default defineConfig({
1929
['meta', { name: 'twitter:card', content: 'summary_large_image' }],
2030
],
2131
themeConfig: {
22-
siteTitle: 'feathers-hooks-common/index.js',
32+
siteTitle: name,
2333
editLink: {
24-
pattern:
25-
'https://github.com/feathersjs-ecosystem/feathers-hooks-common/edit/master/docs/:path',
34+
pattern: `https://github.com/${repository}/edit/${mainBranch}/docs/:path`,
2635
},
2736
lastUpdatedText: 'Last Updated',
2837
socialLinks: [
29-
{
30-
icon: 'twitter',
31-
link: 'https://twitter.com/feathersjs',
32-
},
3338
{
3439
icon: 'discord',
3540
link: 'https://discord.gg/qa8kez8QBx',
3641
},
3742
{
3843
icon: 'github',
39-
link: 'https://github.com/feathersjs-ecosystem/feathers-hooks-common/index.js',
44+
link: `https://github.com/${repository}`,
4045
},
4146
],
4247
logo: '/feathers-hooks-common-logo.png',
@@ -45,8 +50,36 @@ export default defineConfig({
4550
text: 'Guide',
4651
items: [
4752
{ text: 'Overview', link: '/overview' },
48-
{ text: 'Hooks', link: '/hooks/index.js' },
49-
{ text: 'Utilities', link: '/utilities' },
53+
{
54+
text: 'Hooks',
55+
link: '/hooks',
56+
items: utilities
57+
.filter(x => x.category === 'hooks')
58+
.map(x => ({
59+
text: x.title,
60+
link: x.path,
61+
})),
62+
},
63+
{
64+
text: 'Utilities',
65+
link: '/utils',
66+
items: utilities
67+
.filter(x => x.category === 'utils')
68+
.map(x => ({
69+
text: x.title,
70+
link: x.path,
71+
})),
72+
},
73+
{
74+
text: 'Predicates',
75+
link: '/predicates',
76+
items: utilities
77+
.filter(x => x.category === 'predicates')
78+
.map(x => ({
79+
text: x.title,
80+
link: x.path,
81+
})),
82+
},
5083
{ text: 'Migrating', link: '/migrating' },
5184
{ text: 'Guides', link: '/guides' },
5285
],
@@ -58,11 +91,11 @@ export default defineConfig({
5891
items: [
5992
{
6093
text: 'Changelog',
61-
link: 'https://github.com/feathersjs-ecosystem/feathers-hooks-common/blob/master/CHANGELOG.md',
94+
link: `https://github.com/${repository}/blob/${mainBranch}/CHANGELOG.md`,
6295
},
6396
{
6497
text: 'Contributing',
65-
link: 'https://github.com/feathersjs-ecosystem/feathers-hooks-common/blob/master/.github/contributing.md',
98+
link: `https://github.com/${repository}/blob/${mainBranch}/.github/contributing.md`,
6699
},
67100
],
68101
},
@@ -77,4 +110,36 @@ export default defineConfig({
77110
indexName: 'feathers-hooks',
78111
},
79112
},
113+
markdown: {
114+
codeTransformers: [
115+
transformerTwoslash({
116+
twoslashOptions: {
117+
compilerOptions: {
118+
paths: {
119+
'feathers-commons': [resolve(__dirname, '../../src/index.ts')],
120+
'feathers-commons/hooks': [resolve(__dirname, '../../src/hooks/index.ts')],
121+
'feathers-commons/utils': [resolve(__dirname, '../../src/utils/index.ts')],
122+
'feathers-commons/predicates': [resolve(__dirname, '../../src/predicates/index.ts')],
123+
'feathers-commons/resolvers': [resolve(__dirname, '../../src/resolvers/index.ts')],
124+
},
125+
},
126+
},
127+
}),
128+
],
129+
// Explicitly load these languages for types hightlighting
130+
languages: ['js', 'ts'],
131+
},
132+
vite: {
133+
server: {
134+
fs: {
135+
allow: [resolve(__dirname, '../../src')],
136+
},
137+
},
138+
plugins: [
139+
MarkdownTransform({
140+
vitepressDirectory: resolve(__dirname, '../'),
141+
}),
142+
tailwindcss(),
143+
],
144+
},
80145
})

‎docs/.vitepress/meta.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
1-
export const name = 'feathers-hooks-common/index.js'
1+
export const name = 'feathers-commons'
22
export const description = 'Common hooks and utils for FeathersJS apps'
33

4+
export const repository = 'feathersjs-ecosystem/feathers-hooks-common'
5+
export const mainBranch = 'master'
6+
47
export const ogUrl = 'https://hooks-common.feathersjs.com/'
58
export const ogImage = 'https://hooks-common.feathersjs.com/feathers-hooks-common-logo.png'

‎docs/.vitepress/plugins/markdownTransform.ts‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
import type { Plugin } from 'vite'
2+
3+
import { discoverUtilities, type Utility } from '../utilities'
4+
import md from './utility'
5+
6+
export type MarkdownTransformOptions = {
7+
srcDir?: string
8+
pattern?: string
9+
exclude?: string[]
10+
vitepressDirectory: string
11+
}
12+
13+
export function MarkdownTransform(options: MarkdownTransformOptions): Plugin {
14+
const {
15+
srcDir = '../../src',
16+
pattern = '**/*.md',
17+
exclude = ['**/node_modules/**', '**/dist/**'],
18+
vitepressDirectory,
19+
} = options ?? {}
20+
21+
let utilitiesList: Utility[] = []
22+
23+
return {
24+
name: 'feathers-commons-md-transform',
25+
enforce: 'pre',
26+
async buildStart() {
27+
const result = await discoverUtilities()
28+
utilitiesList = result
29+
},
30+
async transform(code, id) {
31+
if (!id.match(/\.md\b/)) return null
32+
33+
const slug = id.replace(vitepressDirectory, '')
34+
35+
const utility = utilitiesList.find(x => x.pathMd === slug)
36+
if (!utility) {
37+
console.warn(`Utility not found for slug: ${slug}`)
38+
return null
39+
}
40+
41+
return md(utility)
42+
},
43+
// configureServer(server) {
44+
// const watcher = server.watcher
45+
46+
// watcher.add(`${srcDir}/**/*.md`)
47+
48+
// watcher.on('change', async filePath => {
49+
// console.log(`🔄 Utility changed: ${filePath}`)
50+
// if (filePath.includes(srcDir) && filePath.endsWith('.md')) {
51+
// console.log(`📝 Utility changed: ${filePath}`)
52+
// await discoverUtilities(options)
53+
54+
// // Invalidate virtual modules
55+
// const moduleGraph = server.moduleGraph
56+
// const virtualModules = Array.from(moduleGraph.urlToModuleMap.keys()).filter(
57+
// url => url.startsWith(VIRTUAL_UTILITY_PREFIX) || url === VIRTUAL_UTILITIES_LIST,
58+
// )
59+
60+
// virtualModules.forEach(url => {
61+
// const module = moduleGraph.getModuleById(url)
62+
// if (module) {
63+
// server.reloadModule(module)
64+
// }
65+
// })
66+
// }
67+
// })
68+
69+
// watcher.on('add', async filePath => {
70+
// if (filePath.includes(srcDir) && filePath.endsWith('.md')) {
71+
// console.log(`➕ New utility: ${filePath}`)
72+
// await discoverUtilities(options)
73+
// }
74+
// })
75+
76+
// watcher.on('unlink', async filePath => {
77+
// if (filePath.includes(srcDir) && filePath.endsWith('.md')) {
78+
// console.log(`➖ Utility removed: ${filePath}`)
79+
// await discoverUtilities(options)
80+
// }
81+
// })
82+
// },
83+
}
84+
}

‎docs/.vitepress/plugins/utility.ts‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
import type { Utility } from '../utilities'
2+
import dedent from 'dedent'
3+
4+
const arr = (value: any[]) => {
5+
if (!value || !value.length) return '[]'
6+
const val = value
7+
.map(x => {
8+
if (typeof x === 'string') return `'${x}'`
9+
if (typeof x === 'number') return x.toString()
10+
return JSON.stringify(x)
11+
})
12+
.join(', ')
13+
14+
return `[${val}]`
15+
}
16+
17+
export default (utility: Utility) => {
18+
const code = [
19+
dedent`# ${utility.title}
20+
21+
[Source Code](${utility.sourceUrl})
22+
23+
${utility.description}
24+
25+
\`\`\`ts twoslash
26+
import { ${utility.name} } from 'feathers-commons/${utility.category}';
27+
\`\`\` `,
28+
]
29+
30+
if (utility.hook) {
31+
code.push(dedent`
32+
<HookTable :type="${arr(utility.hook.type)}" :method="${arr(utility.hook.method)}" :multi="${utility.hook.multi}" source="https://github.com/feathersjs-ecosystem/feathers-hooks-common/blob/master/src/hooks/required.ts" />
33+
`)
34+
}
35+
36+
code.push(utility.content)
37+
38+
return code.join('\n\n')
39+
}

‎docs/.vitepress/style/main.css‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
@import "tailwindcss";
2+
13
/**
24
* Colors
35
* -------------------------------------------------------------------------- */

‎docs/.vitepress/theme/components/HookTable.vue‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
<template>
2+
<table>
3+
<thead>
4+
<tr>
5+
<th>type</th>
6+
<th>methods</th>
7+
<th>multi</th>
8+
<th>details</th>
9+
</tr>
10+
</thead>
11+
<tbody>
12+
<tr>
13+
<td>{{ typeOrder.join(", ") }}</td>
14+
<td>{{ methodOrder.join(", ") }}</td>
15+
<td>{{ typeof multi === 'boolean' ? multi ? 'yes' : 'no' : multi }}</td>
16+
<td><a :href="source" target="_blank">source</a></td>
17+
</tr>
18+
</tbody>
19+
</table>
20+
</template>
21+
22+
<script setup lang="ts">
23+
const props = withDefaults(defineProps<{
24+
type: HookType[]
25+
method: string[];
26+
multi: boolean | string;
27+
source: string;
28+
}>(), {
29+
type: () => ([]),
30+
method: () => ([]),
31+
});
32+
33+
const typeOrder = computed(() => {
34+
const result: HookType[] = [];
35+
36+
hookTypeValues.forEach((type) => {
37+
if (props.type.includes(type)) {
38+
result.push(type);
39+
}
40+
});
41+
42+
return result;
43+
})
44+
45+
const methodOrder = computed(() => {
46+
const result: HookMethod[] = [];
47+
48+
if (props.method.includes('all')) {
49+
return ['all']
50+
}
51+
52+
methodValues.forEach((method) => {
53+
if (props.method.includes(method)) {
54+
result.push(method);
55+
}
56+
});
57+
58+
return result;
59+
});
60+
</script>
61+
62+
<script lang="ts">
63+
import { computed } from 'vue';
64+
65+
const hookTypeValues = ['before', 'after', 'around', 'error'] as const;
66+
type HookType = (typeof hookTypeValues)[number];
67+
68+
const methodValues = ['find', 'get', 'create', 'update', 'patch', 'remove'] as const;
69+
type HookMethod = (typeof methodValues)[number];
70+
</script>

‎docs/.vitepress/theme/index.ts‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
1-
import Theme from 'vitepress/theme'
1+
import DefaultTheme from 'vitepress/theme'
2+
import TwoslashFloatingVue from '@shikijs/vitepress-twoslash/client'
3+
4+
import type { Theme } from 'vitepress'
5+
import HookTable from './components/HookTable.vue'
6+
27
import '../style/main.css'
8+
import '@shikijs/vitepress-twoslash/style.css'
39

410
export default {
5-
...Theme,
6-
}
11+
extends: DefaultTheme,
12+
enhanceApp({ app }) {
13+
app.use(TwoslashFloatingVue)
14+
app.component('HookTable', HookTable)
15+
},
16+
} satisfies Theme

0 commit comments

Comments
 (0)