桌面应用【免费下载链接】QOwnNotesQOwnNotes is a plain-text file notepad and todo-list manager with Markdown support and Nextcloud / ownCloud integration.项目地址https://gitcode.com/gh_mirrors/qo/QOwnNotes点击查看免费下载QOwnNotes 官方网页qownnotes.org由仓库webpage/目录承载是一套基于 VuePress 2next 版本 Vuetify 3 的静态站点包含文档、博客、多语言翻译与 SEO 输出。本文以 webpage/README.md 为核心结合 package.json、scripts/run-dev.sh、src/.vuepress/config.js 等真实源码讲清楚如何在本地跑起带热更新的开发服务器、如何执行生产构建以及样式与菜单配置分别改在哪里帮助你完整掌握该项目官网前端的开发与定制方法。一、开发环境与目录结构webpage/README.md明确列出的开发依赖只有一项Node.jsnodejs.org 官方安装包即可。仓库 package.json 确认了工程采用 ESMtype: module主要开发依赖为依赖版本作用vuepress/vuepress/bundler-vitenextVuePress 2.x站点框架与 Vite 打包器vuepress/theme-defaultnext默认主题导航/侧边栏/编辑链接vuepress/plugin-docsearchnextAlgolia DocSearch 全文搜索vuepress/plugin-markdown-chartnextMermaid 图表支持vuepress/plugin-markdown-extnext任务列表等 Markdown 扩展vuepress/plugin-seo/plugin-sitemap/plugin-feednextSEO meta、sitemap、RSS/Atom 输出vuetify3.11.5组件库首页轮播、RSS 块等自定义组件sass^1.83.0SCSS 样式编译markdown-itmarkdown-it-meta^14从 Markdown 元数据提取标题/日期生成侧边栏与博客数据playwright/test1.57.0浏览器端到端测试webpage/下的关键目录与文件webpage/src/全部站点内容按getting-started/、installation/、editor/、scripting/、contributing/、faq/、blog/组织另有de/、fr/、it/、es/、fa/、nl/、hu/、ar/、pl/、ko/等翻译目录webpage/src/.vuepress/站点工程目录含 config.js核心配置、styles/index.scss样式、theme/index.js 与 theme/layouts/Layout.vue自定义主题、utils.js侧边栏/博客目录生成工具、components/BlogIndex.vue、ScreenshotCarousel.vue、RssBlock.vue等 Vuetify 组件、public/静态资源webpage/scripts/构建辅助脚本核心是 run-dev.shwebpage/tests/Playwright 端到端测试basic.spec.js、rss.spec.js、sitemap.spec.js、mermaid.spec.js、translations.spec.js等 12 个文件工程配套文件docker-compose.yml、nginx.conf、justfile、playwright.config.js。二、本地开发流程npm run devREADME 给出的开发命令序列如下# clone the repository git clone https://github.com/pbek/QOwnNotes.git # change to the webpage directory cd QOwnNotes/webpage # install dependencies npm install # build the webpage in development mode with hot reloading npm run dev执行完毕后在浏览器打开http://0.0.0.0:8080/即可访问本地站点对源码的任何修改都会通过热更新自动反映到页面。npm run dev并不只是简单地启动 VuePress它在 package.json 中被映射为./scripts/run-dev.sh查看 scripts/run-dev.sh 可以看到完整的启动流水线# 1. 复制截图资源到站点 public 目录缺失时仅警告、不中断 cp -R ../screenshots src/.vuepress/public 2/dev/null || echo ⚠️ Screenshots not found, skipping # 2. 复制根目录 CHANGELOG.md 作为站点 /changelog 页面 cp ../CHANGELOG.md src/changelog.md 2/dev/null || echo ⚠️ CHANGELOG.md not found, skipping # 3. 生成博客索引数据 node scripts/generate-blog-data.js # 4. 启动 VuePress 2 开发服务器 npx vuepress dev src其中第 3 步的 scripts/generate-blog-data.js 值得展开它用glob扫描src/blog/**/*.md跳过README.md用markdown-itmarkdown-it-meta解析每篇文章的元数据从 front matter 或首个 H1 提取标题从文件名YYYY-MM-DD-xxx.md或 front matter 的date/order字段提取日期按日期倒序排序后写入src/.vuepress/blog-data.json。该文件被 components/BlogIndex.vue 消费以渲染博客首页列表且被 git 忽略、每次 dev/build 重新生成——这意味着你新增一篇src/blog/2026-10-09-my-post.md后下次npm run dev它就自动出现在博客索引中无需手工维护列表。npx vuepress dev src的src参数指定了站点源目录即 VuePress 约定src/.vuepress为工程目录src下其余 Markdown 为页面内容。三、生产构建npm run build按 webpage/README.md 的说明npm run build会以生产模式构建网页产物输出到webpage/src/.vuepress/dist。该命令同样先执行资源复制与博客数据生成再调用 VuePress 的build子命令package.json 中映射为./scripts/run-build.sh。package.json 中还有一组 Playwright 测试脚本用于对已部署的站点做端到端验证playwright:test: TEST_ENVprod playwright test, playwright:test:next: TEST_ENVnext playwright test, playwright:test:local: TEST_ENVlocal playwright test, playwright:test:local-docker: TEST_ENVlocal-docker playwright test环境选择逻辑在 webpage/config.js 中通过TEST_ENV环境变量在prodwww.qownnotes.org、nextnext.qownnotes.org、localhttp://localhost:8080、local-dockerhttp://localhost:8081四套 baseURL 配置中取用未知环境会抛出带可选值列表的异常。playwright.config.js 在 CI 下把超时时间放大 3 倍、开启 2 次重试并用forbidOnly防止test.only误提交。用 Docker / justfile 跑开发环境除直接npm run dev外仓库还封装了容器化与任务运行方式docker-compose.ymldev服务用node:22-alpine挂载当前目录在容器内执行npm install npm run dev宿主8080:8080端口映射与本地开发一致web服务从 Dockerfile 构建生产镜像以8081:80暴露正好对应local-docker测试环境justfile 提供just dev、just build、just install、just clean清理dist、.cache、.temp、just open-browser打开http://localhost:8080/、just playwright-test等配方方便无npm肌肉记忆的开发者使用。四、核心站点配置src/.vuepress/config.jsREADME 指出菜单和配置存放在 config.js。webpage/src/.vuepress/config.js约 1100 行是整个站点行为的总控文件结构分为五块。1. 站点元信息与 Vite 打包器export default defineUserConfig({ lang: en-US, title: QOwnNotes, // description 来自 package.json 的 description 字段 description: description, // 关闭 SSR 预加载规避 CSS 导入问题 shouldPreload: false, shouldPrefetch: false, bundler: viteBundler({ viteOptions: { ssr: { noExternal: [vuetify] }, // Vuetify 需要在 SSR 中打包 build: { rollupOptions: { output: { // 资产文件去掉内容哈希后缀保持原始文件名 assetFileNames: (assetInfo) { /* ...assets/${baseName}${ext} */ }, }, }, }, }, }), // ... });三个细节值得注意description直接require(../../package.json)复用包描述保证站点 meta 与 npm 元数据一致ssr.noExternal: [vuetify]配合根目录的 css-loader.mjs一个拦截.css导入并返回空模块的 Node ESM loader 钩子解决 Vuetify CSS 在 Node SSR 环境下无法被原生解析的问题assetFileNames自定义函数刻意去除构建产物的哈希后缀使静态资源文件名在版本间保持稳定便于外部链接与缓存策略。2. 插件链搜索、Mermaid、任务列表、SEO、Sitemap、RSSplugins数组按序注册六个插件关键参数如下docsearchPluginAlgolia 索引qownnotesappIdLP8PS829KJ并按 locale 为/、/de/、/it/、/fr/、/es/、/fa/、/nl/、/hu/、/ar/、/pl/、/ko/各语言分别配置搜索框占位文案与按钮翻译markdownChartPluginmermaid: true使文档中可用的 Mermaid 流程图语法生效对应测试 tests/mermaid.spec.jsmarkdownExtPlugintasklist: true开启- [x]任务列表渲染seoPluginhostname/canonical均为https://www.qownnotes.orgogp回调按页面 front matter 的image字段生成og:image相对路径自动补全为站点绝对地址缺省回退到https://www.qownnotes.org/screenshots/screenshot.png并输出twitter:cardsummary_large_image等 Twitter 卡片字段sitemapPlugin生成 sitemap 并排除/404.htmlfeedPlugin同时输出rss.xml、feed.atom、feed.json三种订阅格式filter只收录frontmatter.feed为真或路径以blog/开头的文章sorter按 front matterdate倒序排列。head数组则注入theme-color#3eaf7c、favicon/favicon.png、Material Design Icons 字体样式表、FeedBurner 的 Releases/Blog 双 RSS 链接以及 Mastodon 身份声明链接relme——这些正是 tests/head-tags.spec.js 校验的对象。3. 多语言 localeslocales声明了 11 个语言路由/en-US、/de/、/it/、/fr/、/es/、/fa/、/nl/、/hu/、/ar/、/pl/、/ko/与 webpage/src/ 下同名目录一一对应。英文站点启用editLink: true并配置docsBranch: main、docsDir: webpage/src因此每页底部会出现 Help us improve this page! 编辑链接翻译站点统一editLink: false仅英文源可提交修改。4. 导航栏与侧边栏的生成机制这是 config.js 中最有工程含量的部分。各栏目页面清单以纯路径数组声明const gettingStartedNavItems [ getting-started/overview, getting-started/concept, getting-started/markdown, getting-started/importing-notes, getting-started/cli-parameters, getting-started/browser-extension, getting-started/homepage-suggestion-api, getting-started/command-line-snippet-manager, getting-started/qownnotes-tui, getting-started/qownnotes-android, getting-started/web-app, getting-started/qownnotesapi, getting-started/note-relations, getting-started/searching, getting-started/shortcuts, getting-started/git-versioning, ]; // installationNavItems: 21 个发行版安装指南 // editorNavItems: spellchecking / languagetool / harper / markdownlsp / ai / time-formats // scriptingNavItems、contributingNavItems、faqNavItems 同理英文站点的侧边栏直接引用这些数组而翻译语言版本通过 src/.vuepress/utils.js 中的工具函数做路径重写getNavItemsForLanguage(items, de)把getting-started/overview映射为de/getting-started/overview实现同一份页面清单 → 各语言目录的批量转换getChildren(src, blog, true)用glob扫描src/blog/**/*.md借助markdown-it-meta读取 front matter 的order值排序README自动归一为目录索引页生成 Blog 栏目动态目录getBlogChildrenWithTitles(src, blog, true)在上一项基础上额外提取每篇博客的首个 H1 作为菜单显示文本元数据title优先。因此新增一篇博客或翻译文档后侧边栏会随之更新无需手工改菜单而contactNavItemsGitHub Issues 提问/报 Bug、Telegram/Matrix/Gitter/IRC/Mastodon 等社区入口是静态数组直接作为 Contact 下拉项。五、样式定制SCSS 在哪里改README 指出样式主要存放在 index.scss。webpage/src/.vuepress/styles/index.scss 顶部注释说明了两件事改动移动端汉堡菜单断点需修改 palette.scss 中的$MQMobile变量默认断点 719px常规排版微调直接在本文件覆盖。文件中的典型覆盖示例// 正文最大宽度加宽到 900px .vp-page [vp-content] { max-width: 900px; } // 首页 hero 区 logo 高度限制 .vp-home header.vp-hero img { max-height: 500px !important; height: auto !important; } // Vuetify 的 * { margin: 0 } 会清掉段落间距这里恢复 p, ul, ol { margin: 16px 0; }最后一段注释点出了两套 UI 体系共存时的常见坑Vuetify 的全局 reset 会清掉 VuePress 内容的默认边距需要手工补回。主题侧则由 theme/index.js 基于vuepress/theme-default做扩展theme/layouts/Layout.vue 提供整页布局的挂载点首页轮播、RSS 块等 Vuetify 组件即挂在此结构中。六、站点部署配套nginx 与旧版 URL 重定向webpage/nginx.conf 展示了该站点的上线形态对理解构建产物如何被服务很有参考价值80 端口的qownnotes.org/docs.qownnotes.org直接 301 到https://www.qownnotes.orgmap $request_uri $redirect_uri块维护了一张旧 URL 重定向表覆盖老站点www.qownnotes.org如/changelog/QOwnNotes → /changelog.html、/donate → /contributing/donate.html和老docs.qownnotes.org/en/latest/scripting/xxx → /scripting/xxx.html一类保证多年积累的外部链接不失效location /api/与location /rss/project_version/qownnotes.rss反向代理到qownnotes-api上游——这与 docker-compose.yml 中web服务的extra_hosts: qownnotes-api:127.0.0.1呼应即容器内静态站点与 API 服务解耦部署静态资源根目录为/usr/share/nginx/html即上文dist构建产物或其副本的落点。七、小结与快速核对清单围绕 webpage/README.md 的三条主线本地验证一遍即可确认环境工作正常开发cd QOwnNotes/webpage npm install npm run dev浏览器访问http://0.0.0.0:8080/修改任意src/**/*.md观察热更新新博客文章确认自动进入blog-data.json索引构建npm run build后检查src/.vuepress/dist产物关注无哈希资产文件名、rss.xml/feed.atom/feed.json、sitemap 是否生成定制改样式到 src/.vuepress/styles/index.scss断点在 palette.scss改菜单/插件/SEO/多语言到 src/.vuepress/config.js部署形态参考 nginx.conf容器化参考 docker-compose.yml 与 justfile。需要说明的适用前提以上流程基于仓库当前的 VuePress 2next版本 Vite 技术栈依赖 package-lock.json 锁定的依赖版本npm run dev中截图与 CHANGELOG 的复制步骤要求webpage/与screenshots/、CHANGELOG.md保持仓库内的相对位置单独拷贝webpage/目录到其他位置时这些步骤只会给出警告而不会失败。赞分享桌面应用【免费下载链接】QOwnNotesQOwnNotes is a plain-text file notepad and todo-list manager with Markdown support and Nextcloud / ownCloud integration.项目地址https://gitcode.com/gh_mirrors/qo/QOwnNotes点击查看免费下载相关推荐Arthas 文档网站本地运行与构建指南基于 VuePress 2 的官方站点开发详解Arthas 文档网站本地运行与构建指南基于 VuePress 2 的官方站点开发详解 Arthas 是阿里巴巴开源的 Java 在线诊断工具其官方文档网站开发工具可观测性调试器性能剖析Locomotive Boilerplate 前端脚手架实战指南基于 Locomotive Scroll 的官网项目搭建与构建Locomotive Boilerplate 前端脚手架实战指南基于 Locomotive Scroll 的官网项目搭建与构建 output 本文以仓库中的Return YouTube Dislike 官网搭建指南基于 Nuxt 2 的构建、开发与目录结构解析Return YouTube Dislike 官网搭建指南基于 Nuxt 2 的构建、开发与目录结构解析 Website/READMEnl.md retur开发工具上一篇OBS Studio直播录制终极指南3个步骤打造专业级视频内容下一篇告别臃肿的Windows 10用Windows10Debloater一键清理系统垃圾创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考