From cf938779dded46f6945fba1f52baff7ec0e19a90 Mon Sep 17 00:00:00 2001 From: wanxp <977741432@qq.com> Date: Sat, 11 May 2024 16:04:34 +0800 Subject: [PATCH] add project wiki github pages --- doc/01_introduction.md | 47 +++++++++ doc/10_install.md | 18 ++++ doc/20_howtouse.md | 17 +++ doc/20_howtouse_setting.md | 11 ++ doc/30_function.md | 12 +++ doc/35_support_variables.md | 42 ++++++++ doc/60_special_use.md | 13 +++ doc/70_effect.md | 17 +++ doc/80_develop.md | 22 ++++ doc/90_thanks.md | 8 ++ doc/94_disclaimer.md | 12 +++ doc/99_support.md | 10 ++ doc/Gemfile | 3 + doc/Gemfile.lock | 21 ++-- doc/Obsidian-Douban-BlueTopaz.md | 21 +++- doc/Obsidian-Douban-TimeLine.md | 24 ++++- doc/README.md | 174 ------------------------------- doc/_config.yml | 2 +- doc/index.md | 35 ------- 19 files changed, 284 insertions(+), 225 deletions(-) create mode 100644 doc/01_introduction.md create mode 100644 doc/10_install.md create mode 100644 doc/20_howtouse.md create mode 100644 doc/20_howtouse_setting.md create mode 100644 doc/30_function.md create mode 100644 doc/35_support_variables.md create mode 100644 doc/60_special_use.md create mode 100644 doc/70_effect.md create mode 100644 doc/80_develop.md create mode 100644 doc/90_thanks.md create mode 100644 doc/94_disclaimer.md create mode 100644 doc/99_support.md delete mode 100644 doc/README.md delete mode 100644 doc/index.md diff --git a/doc/01_introduction.md b/doc/01_introduction.md new file mode 100644 index 0000000..8cd9fe2 --- /dev/null +++ b/doc/01_introduction.md @@ -0,0 +1,47 @@ +--- +title: 简介 +layout: home +nav_order: 100 +--- + + +这是一款[Obsidian](https://obsidian.md/)的插件, 用于导入[豆瓣](https://www.douban.com/)中的 _电影、书籍、音乐、电视剧、日记、游戏_ +甚至是 _你标记过的书影音_ , 包含你的评分、观看日期、评论、阅读状态等信息. + +![background](./background.png) + +## 基本功能 +- ☑️ 导入电影、电视剧、书籍、音乐、游戏、日记 +- ☑️ 同步个人听过/看过的电影、电视剧、书籍、音乐 +- ☑️ 导入个人的评论,评论时间,阅读状态,个人评分 +- ☑️ 支持保存封面至本地 +- ☑️ 支持自定义参数 + +## 交流社群 + + + + + + + +

+ + + + + + + + + + + +
+ + + CodeFactor + +

+ +[Just the Docs repo]: https://github.com/Wanxp/obsidian-douban diff --git a/doc/10_install.md b/doc/10_install.md new file mode 100644 index 0000000..de6be4e --- /dev/null +++ b/doc/10_install.md @@ -0,0 +1,18 @@ +--- +title: 如何安装 +layout: home +nav_order: 200 +--- + +## 如何安装 +### 从Obsidian插件中心 +1. 进入Obsidian插件中心 +2. 搜索obsidian-douban +3. 安装 +4. 开启插件 + +### 手动安装 + +1. 从[Github release](https://github.com/Wanxp/obsidian-douban/releases) 页面下载 `main.js`, `manifest.json`, `styles.css` +2. 将下载的文件复制到你的Obsidian文档根目录下的`/.obsidian/plugins/obsidian-douban`路径,若不存在则新建文件夹(注意.obsidian文件夹可能是个隐藏为文件夹) +3. 在obsidian插件中心开启当前插件功能 diff --git a/doc/20_howtouse.md b/doc/20_howtouse.md new file mode 100644 index 0000000..0fdaba8 --- /dev/null +++ b/doc/20_howtouse.md @@ -0,0 +1,17 @@ +--- +title: 如何使用 +layout: home +nav_order: 300 +--- +## 如何使用 +## 搜索 +使用方式: 输入Ctrl + P,输入“豆瓣”或“Douban”,选择搜索并使用 +- 搜索数据并创建笔记 +- 通过当前文件名搜索 +- 通过输入文本搜索 + ![search_and_create](img/search_and_create_note.gif) + + +## 同步 +- 同步个人的观影、观剧、阅读、游戏、音乐记录 + ![Sync Data From Douban](img/sync_data_from_douban.gif) diff --git a/doc/20_howtouse_setting.md b/doc/20_howtouse_setting.md new file mode 100644 index 0000000..8a232b4 --- /dev/null +++ b/doc/20_howtouse_setting.md @@ -0,0 +1,11 @@ +--- +title: 设置 +layout: home +nav_order: 350 +--- + +## 设置 +- 设置豆瓣账号(可选,可使用少部分功能) +- 设置导入模板(可选,不设置的情况下使用默认模板) +- 设置导入路径(可选,不设置的情况下使用默认路径) + diff --git a/doc/30_function.md b/doc/30_function.md new file mode 100644 index 0000000..5d09dbc --- /dev/null +++ b/doc/30_function.md @@ -0,0 +1,12 @@ +--- +title: 功能 +layout: home +nav_order: 400 + +--- +## 功能 +- ☑️ 导入电影、电视剧、书籍、音乐、游戏、日记 +- ☑️ 同步个人听过/看过的电影、电视剧、书籍、音乐 +- ☑️ 导入个人的评论,评论时间,阅读状态,个人评分 +- ☑️ 支持保存封面至本地 +- ☑️ 支持自定义参数 diff --git a/doc/35_support_variables.md b/doc/35_support_variables.md new file mode 100644 index 0000000..7d573bc --- /dev/null +++ b/doc/35_support_variables.md @@ -0,0 +1,42 @@ +--- +title: 支持的参数 +layout: home +nav_order: 500 +--- + +## 支持的字段 +(若有缺少想导入的字段, 欢迎提issues反馈) + +| 字段 | 电影 | 电视剧 | 书籍 | 音乐 | 日记 | 游戏 | 人物 | +|------------------|------------------|-------------------|-------------------|---------------|----------------|---------------|-------| +| id | 豆瓣ID | 豆瓣ID | 豆瓣ID | 豆瓣ID | 豆瓣ID | 豆瓣ID | id | +| title | 电影名称 | 电视剧名称 | 书名 | 音乐名 | 日记标题 | 游戏名称 | 姓名 | +| type | 类型 | 类型 | 类型 | 类型 | 类型 | 类型 | 类型 | +| score | 评分 | 评分 | 评分 | 评分 | 评分 | 评分 | | +| scoreStar | 评分⭐ | 评分⭐ | 评分⭐ | 评分⭐ | 评分⭐ | 评分⭐ | | +| image | 封面 | 封面 | 封面 | 封面 | 图片 | 封面 | 照片 | +| imageData.url | 封面url | 封面url | 封面url | 封面url | 封面url | 封面url | 照片url | +| url | 豆瓣网址 | 豆瓣网址 | 豆瓣网址 | 豆瓣网址 | 豆瓣网址 | 豆瓣网址 | 豆瓣网址 | +| desc | 简介 | 简介 | 内容简介 | 简介 | 简介 | 简介 | 简介 | +| publisher | - | - | 出版社 | 出版者 | 发布者 | 发行商 | - | +| datePublished | 上映日期 | 上映日期 | 出版年 | 发行时间 | 发布时间 | 发行日期 | - | +| yearPublished | 上映年份 | 上映年份 | 出版年份 | 发行年份 | 发布年份 | 发行年份 | - | +| genre | 类型 | 类型 | - | 流派 | - | 类型 | - | +| currentDate | 今日日期 | 今日日期 | 今日日期 | 今日日期 | 今日日期 | 今日日期 | | +| currentTime | 当前时间 | 当前时间 | 当前时间 | 当前时间 | 当前时间 | 当前时间 | | +| myTags | 我标记的标签 | 我标记的标签 | 我标记的标签 | 我标记的标签 | - | 我标记的标签 | | +| myRating | 我的评分 | 我的评分 | 我的评分 | 我的评分 | - | 我的评分 | +| myState | 状态:想看/在看/看过 | 状态:想看/在看/看过 | 状态:想看/在看/看过 | 状态:想听/在听/听过 | - | 状态:想玩/在玩/玩过 | | +| myComment | 我的评语 | 我的评语 | 我的评语 | 我的评语 | - | 我的评语 | | +| myCollectionDate | 我标记的时间 | 我标记的时间 | 我标记的时间 | 我标记的时间 | - | 我标记的时间 | | +| 扩展1 | director:导演* | director:导演* | author:原作者 | actor: 表演者 | author:作者 | aliases:别名 | | +| 扩展2 | author:编剧* | author:编剧* | translator:译者 | albumType:专辑类型 | authorUrl:作者网址 | developer:开发商 | | +| 扩展3 | actor:主演* | actor:主演* | isbn:isbn | medium:介质 | content:日记内容 | platform:平台 | | +| 扩展4 | originalTitle:原作名 | originalTitle:原作名 | originalTitle:原作名 | records:唱片数 | | | | +| 扩展5 | country:国家 | country:国家 | subTitle:副标题 | barcode:条形码 | | | | +| 扩展6 | language:语言 | language:语言 | totalPage:页数 | | | | | +| 扩展7 | time:片长 | time:片长 | series:丛书 | | | | | +| 扩展8 | aliases:又名* | aliases:又名* | menu:目录 | | | | | +| 扩展9 | IMDb | IMDb | price:定价 | | | | | +| 扩展7 | | episode:集数 | binding:装帧 | | | | | +| 扩展8 | | | producer: 出品方 | | | | | diff --git a/doc/60_special_use.md b/doc/60_special_use.md new file mode 100644 index 0000000..49ef530 --- /dev/null +++ b/doc/60_special_use.md @@ -0,0 +1,13 @@ +--- +title: 特殊效果 +layout: home +nav_order: 450 +has_children: true +--- + +## 效果 +1. 结合Timeline插件 __构建个人观影时间线__,请参照[结合timeline插件实现时间线效果](./Obsidian-Douban-TimeLine.md) + ![](./img/obsidian-douban-time-preview-example.gif) + +2. 结合主题 __构建类豆瓣网页效果__,请参照[结合Blue Topaz实现网页效果](./Obsidian-Douban-BlueTopaz.md) + ![](./background.png) diff --git a/doc/70_effect.md b/doc/70_effect.md new file mode 100644 index 0000000..c2bcd24 --- /dev/null +++ b/doc/70_effect.md @@ -0,0 +1,17 @@ +--- +title: 数据影响 +layout: home +nav_order: 600 +--- + +## 数据影响 +注意: 除了在同步书影音数据时勾选 `替换同名文档` 有可能会修改同路径同文档名的笔记外,其余操作均不会修改已有笔记。 + +| 操作 | 条件 | 影响 | 举例 | +|---------|------------------|---------------------------|-----------------------------------------------------------------------------------------------| +| 导入书影音数据 | 默认条件 | 新建一条名为所选条目的笔记 | 如搜索蝙蝠侠并选中导入,则会创建笔记 《蝙蝠侠》 | +| 导入书影音数据 | 已有同名笔记 | 无任何影响,提示已经存在同名笔记,不会修改已有笔记 | 如搜索蝙蝠侠并选中导入,但因存在同路径同名称笔记,则会不会创建笔记 | +| 导入书影音数据 | 配置 `笔记名称`值包含路径 | 若没有此路径则会创建对应文件名 | 如搜索蝙蝠侠并选中导入,配置`笔记名称`值为`/data/{{type}}/{{title}}`,则会创建文件夹`data/电影` | +| 导入书影音数据 | 配置 `保存图片附件`值为勾选 | 则会在`附件存放位置`指定位置保存封面图片 | 如搜索蝙蝠侠并选中导入,配置`附件存放位置`值为`assets`,则会在`assets`文件夹中保存封面文件`p462657443.jpg` | +| 同步书影音数据 | 以上所有 | 以上所有 | 以上所有 | +| 同步书影音数据 | `替换同名文档`值为勾选 | 已经存在 **同路径同文档名** ,直接覆盖 | 如已经存在在`data/Movie/蝙蝠侠.md`,配置`笔记名称`值为`/data/{{type}}/{{title}}`, 同步书影音记录时勾选 `替换同名文档`, 则`data/Movie/蝙蝠侠.md`会被替换成最新 | diff --git a/doc/80_develop.md b/doc/80_develop.md new file mode 100644 index 0000000..40a8e3e --- /dev/null +++ b/doc/80_develop.md @@ -0,0 +1,22 @@ +--- +title: 开发 +layout: home +nav_order: 700 +--- + +## 如何开发调试 + +1. 进入你的Obsidian测试文档文件夹下的`/.obsidian/plugins/` +2. 克隆代码 + `git clone git@github.com:Wanxp/obsidian-douban.git` +3. 进入代码文件夹 + `cd obsidian-douban` +4. install + `npm install` +5. 构建 + `npm run build` +6. 运行 + `npm run dev` +7. 进入Obsidian插件中心重新加载当前插件 +8. 享受开发吧 + diff --git a/doc/90_thanks.md b/doc/90_thanks.md new file mode 100644 index 0000000..c147148 --- /dev/null +++ b/doc/90_thanks.md @@ -0,0 +1,8 @@ +--- +title: 鸣谢 +layout: home +nav_order: 800 +--- +## 鸣谢 +### IDE支持 +[ ](https://www.jetbrains.com/?from=obsidian-douban) diff --git a/doc/94_disclaimer.md b/doc/94_disclaimer.md new file mode 100644 index 0000000..3250bfc --- /dev/null +++ b/doc/94_disclaimer.md @@ -0,0 +1,12 @@ +--- +title: 免责声明 +layout: home +nav_order: 900 +--- + +## 免责声明 +1. 建议使用本插件前,一定要至少有一种方式备份你的数据,以防万一。 +2. 本程序没有爬取任何书影音等内容,只供技术研究使用。没有侵犯书影音作者版权和豆瓣官方利益。如有任何侵权行为,请联系我删除。 +3. 本程序仅供学习交流使用。 +4. 虽然极力避免,但还是有可能纰漏,所以因使用插件造成的损失,由使用者本人承担。不同操作会有何种影响,请参照影响 +5. 使用或修改本插件,即视为同意上述免责声明。 diff --git a/doc/99_support.md b/doc/99_support.md new file mode 100644 index 0000000..588c2d0 --- /dev/null +++ b/doc/99_support.md @@ -0,0 +1,10 @@ +--- +title: 支持 +layout: home +nav_order: 1000 +--- + +## 支持 +愿世界充满爱! +[邮件联系我](mailto:977741432@qq.com) + diff --git a/doc/Gemfile b/doc/Gemfile index 0a1bfe6..66dfc85 100644 --- a/doc/Gemfile +++ b/doc/Gemfile @@ -5,3 +5,6 @@ gem "jekyll", "~> 4.3.3" # installed by `gem jekyll` gem "just-the-docs", "0.8.2" # pinned to the current release # gem "just-the-docs" # always download the latest release + +gem 'json' + diff --git a/doc/Gemfile.lock b/doc/Gemfile.lock index da34973..16ba8b0 100644 --- a/doc/Gemfile.lock +++ b/doc/Gemfile.lock @@ -11,12 +11,8 @@ GEM eventmachine (1.2.7) ffi (1.16.3) forwardable-extended (2.6.0) - google-protobuf (4.26.1) - rake (>= 13) - google-protobuf (4.26.1-arm64-darwin) - rake (>= 13) - google-protobuf (4.26.1-x86_64-linux) - rake (>= 13) + google-protobuf (3.25.3-arm64-darwin) + google-protobuf (3.25.3-x86_64-linux) http_parser.rb (0.8.0) i18n (1.14.4) concurrent-ruby (~> 1.0) @@ -44,6 +40,7 @@ GEM jekyll (>= 3.8, < 5.0) jekyll-watch (2.2.1) listen (~> 3.0) + json (2.7.2) just-the-docs (0.8.2) jekyll (>= 3.8.5) jekyll-include-cache @@ -68,13 +65,10 @@ GEM rexml (3.2.6) rouge (4.2.1) safe_yaml (1.0.5) - sass-embedded (1.75.0) - google-protobuf (>= 3.25, < 5.0) - rake (>= 13.0.0) - sass-embedded (1.75.0-arm64-darwin) - google-protobuf (>= 3.25, < 5.0) - sass-embedded (1.75.0-x86_64-linux-gnu) - google-protobuf (>= 3.25, < 5.0) + sass-embedded (1.69.5-arm64-darwin) + google-protobuf (~> 3.23) + sass-embedded (1.69.5-x86_64-linux-gnu) + google-protobuf (~> 3.23) terminal-table (3.0.2) unicode-display_width (>= 1.1.1, < 3) unicode-display_width (2.5.0) @@ -86,6 +80,7 @@ PLATFORMS DEPENDENCIES jekyll (~> 4.3.3) + json just-the-docs (= 0.8.2) BUNDLED WITH diff --git a/doc/Obsidian-Douban-BlueTopaz.md b/doc/Obsidian-Douban-BlueTopaz.md index 04e8c9a..51da26c 100644 --- a/doc/Obsidian-Douban-BlueTopaz.md +++ b/doc/Obsidian-Douban-BlueTopaz.md @@ -1,13 +1,25 @@ +--- +title: 类豆瓣网页显示 +layout: home +nav_order: 455 +parent: 特殊效果 +render_with_liquid: false +--- + ## 效果如下 ![](./background.png) + ## 适用人群 1. 在豆瓣有标记/评论/评分的习惯的人 比如看完电影,会在豆瓣进行评分或评论。或者阅读完的书籍,进行评分或评论。支持包含:电影、书籍、电视剧、音乐、游戏 + ## 实现步骤 1. 安装[Blue Topaz](https://github.com/PKM-er/Blue-Topaz_Obsidian-css)插件, 可在Obsidian主题搜索中找到 `Blue Topaz` 2. 安装[Obsidian-Douban](https://github.com/Wanxp/obsidian-douban)插件(本插件) 3. 在Obsidian-Douban插件配置中登录Douban 4. 配置需要的模板文件, 在模板中 ==增加== 以下内容,如下所示 + + ````markdown --- @@ -39,12 +51,15 @@ {{myComment}} ```` + + 5. 设置模板为上面的模板 6. 增加数组输出形式 进入插件设置界面,找到[数组输出] ## 模板参考 ### 书籍 + ````markdown --- doubanId: {{id}} @@ -105,5 +120,9 @@ desc: {{desc}} {{menu}} ```` -### 电影、电视剧、音乐、游戏 + +## 电影、电视剧、音乐、游戏 请参照书籍模板 + +## 更多 +此效果来自热心用户的分享,感谢 diff --git a/doc/Obsidian-Douban-TimeLine.md b/doc/Obsidian-Douban-TimeLine.md index 34ac899..1b2eaff 100644 --- a/doc/Obsidian-Douban-TimeLine.md +++ b/doc/Obsidian-Douban-TimeLine.md @@ -1,13 +1,25 @@ +--- +title: 看剧时间线 +layout: home +nav_order: 456 +parent: 特殊效果 +render_with_liquid: false +--- + ## 效果如下 ![](./img/obsidian-douban-time-preview-example.gif) + ## 适用人群 1. 在豆瓣有标记/评论/评分的习惯的人 比如看完电影,会在豆瓣进行评分或评论。或者阅读完的书籍,进行评分或评论。支持包含:电影、书籍、电视剧、音乐、游戏 + ## 实现步骤 1. 安装[Timelines](https://github.com/Darakah/obsidian-timelines)插件 2. 安装[Obsidian-Douban](https://github.com/Wanxp/obsidian-douban)插件(本插件) 3. 在Obsidian-Douban插件配置中登录Douban 4. 配置同步需要的模板 电影/书籍的模板中的frontmatter,在frontmatter中 **增加** 特定tags(根据自己的需要指定),用于需要过滤成为timeline的笔记,如增加tags:`我看过的电影` + + ````markdown --- tags: 我看过的电影 @@ -24,14 +36,20 @@ data-title='{{title}}' data-img='{{image}}' 6. 选择上述模板导入 电影/书籍...,操作方式是打开obsidian命令窗口,输入豆瓣,找到导入功能,在导入界面配置 选择模板进行导入 7. 导入需要一定时间,每条内容导入需要15-30s左右,所有有导入完成后会有导入汇总 8. 导入完成后,新建一个笔记,笔记内容加入timeline的代码块,代码块的内容就是你上面指定的tags的内容,如`我看过的电影`,代码块如下: + ````markdown ```timeline 我看过的电影 ``` ```` + + 9. 预览这个笔记就能看出已经出现了时间线 + ## 模板参考 ### 电影 + + ````markdown --- doubanId: {{id}} @@ -66,7 +84,11 @@ data-title='{{title}}' data-img='{{image}}' data-class = "custom-my-movie-time-line">{{myComment}} |简介: {{desc}} ```` -### 书籍、电视剧、音乐、游戏 + + +## 书籍、电视剧、音乐、游戏 请参照电影模板 + ## 更多 +此效果来自热心用户的分享,感谢[![](https://img.shields.io/badge/GitHub-eryajf-blue)](https://github.com/eryajf) 参照讨论 [结合timeline插件的妙用](https://github.com/Wanxp/obsidian-douban/issues/19#issuecomment-1428307130) diff --git a/doc/README.md b/doc/README.md deleted file mode 100644 index 362efd4..0000000 --- a/doc/README.md +++ /dev/null @@ -1,174 +0,0 @@ -# just-the-docs-template - -This is a *bare-minimum* template to create a [Jekyll] site that: - -- uses the [Just the Docs] theme; -- can be built and published on [GitHub Pages]; -- can be built and previewed locally, and published on other platforms. - -More specifically, the created site: - -- uses a gem-based approach, i.e. uses a `Gemfile` and loads the `just-the-docs` gem; -- uses the [GitHub Pages / Actions workflow] to build and publish the site on GitHub Pages. - -To get started with creating a site, simply: - -1. click "[use this template]" to create a GitHub repository -2. go to Settings > Pages > Build and deployment > Source, and select GitHub Actions - -If you want to maintain your docs in the `docs` directory of an existing project repo, see [Hosting your docs from an existing project repo](#hosting-your-docs-from-an-existing-project-repo). - -After completing the creation of your new site on GitHub, update it as needed: - -## Replace the content of the template pages - -Update the following files to your own content: - -- `index.md` (your new home page) -- `README.md` (information for those who access your site repo on GitHub) - -## Changing the version of the theme and/or Jekyll - -Simply edit the relevant line(s) in the `Gemfile`. - -## Adding a plugin - -The Just the Docs theme automatically includes the [`jekyll-seo-tag`] plugin. - -To add an extra plugin, you need to add it in the `Gemfile` *and* in `_config.yml`. For example, to add [`jekyll-default-layout`]: - -- Add the following to your site's `Gemfile`: - - ```ruby - gem "jekyll-default-layout" - ``` - -- And add the following to your site's `_config.yml`: - - ```yaml - plugins: - - jekyll-default-layout - ``` - -Note: If you are using a Jekyll version less than 3.5.0, use the `gems` key instead of `plugins`. - -## Publishing your site on GitHub Pages - -1. If your created site is `YOUR-USERNAME/YOUR-SITE-NAME`, update `_config.yml` to: - - ```yaml - title: YOUR TITLE - description: YOUR DESCRIPTION - theme: just-the-docs - - url: https://YOUR-USERNAME.github.io/YOUR-SITE-NAME - - aux_links: # remove if you don't want this link to appear on your pages - Template Repository: https://github.com/YOUR-USERNAME/YOUR-SITE-NAME - ``` - -2. Push your updated `_config.yml` to your site on GitHub. - -3. In your newly created repo on GitHub: - - go to the `Settings` tab -> `Pages` -> `Build and deployment`, then select `Source`: `GitHub Actions`. - - if there were any failed Actions, go to the `Actions` tab and click on `Re-run jobs`. - -## Building and previewing your site locally - -Assuming [Jekyll] and [Bundler] are installed on your computer: - -1. Change your working directory to the root directory of your site. - -2. Run `bundle install`. - -3. Run `bundle exec jekyll serve` to build your site and preview it at `localhost:4000`. - - The built site is stored in the directory `_site`. - -## Publishing your built site on a different platform - -Just upload all the files in the directory `_site`. - -## Customization - -You're free to customize sites that you create with this template, however you like! - -[Browse our documentation][Just the Docs] to learn more about how to use this theme. - -## Hosting your docs from an existing project repo - -You might want to maintain your docs in an existing project repo. Instead of creating a new repo using the [just-the-docs template](https://github.com/just-the-docs/just-the-docs-template), you can copy the template files into your existing repo and configure the template's Github Actions workflow to build from a `docs` directory. You can clone the template to your local machine or download the `.zip` file to access the files. - -### Copy the template files - -1. Create a `.github/workflows` directory at your project root if your repo doesn't already have one. Copy the `pages.yml` file into this directory. GitHub Actions searches this directory for workflow files. - -2. Create a `docs` directory at your project root and copy all remaining template files into this directory. - -### Modify the GitHub Actions workflow - -The GitHub Actions workflow that builds and deploys your site to Github Pages is defined by the `pages.yml` file. You'll need to edit this file to that so that your build and deploy steps look to your `docs` directory, rather than the project root. - -1. Set the default `working-directory` param for the build job. - - ```yaml - build: - runs-on: ubuntu-latest - defaults: - run: - working-directory: docs - ``` - -2. Set the `working-directory` param for the Setup Ruby step. - - ```yaml - - name: Setup Ruby - uses: ruby/setup-ruby@v1 - with: - ruby-version: '3.1' - bundler-cache: true - cache-version: 0 - working-directory: '${{ github.workspace }}/docs' - ``` - -3. Set the path param for the Upload artifact step: - - ```yaml - - name: Upload artifact - uses: actions/upload-pages-artifact@v1 - with: - path: "docs/_site/" - ``` - -4. Modify the trigger so that only changes within the `docs` directory start the workflow. Otherwise, every change to your project (even those that don't affect the docs) would trigger a new site build and deploy. - - ```yaml - on: - push: - branches: - - "main" - paths: - - "docs/**" - ``` - -## Licensing and Attribution - -This repository is licensed under the [MIT License]. You are generally free to reuse or extend upon this code as you see fit; just include the original copy of the license (which is preserved when you "make a template"). While it's not necessary, we'd love to hear from you if you do use this template, and how we can improve it for future use! - -The deployment GitHub Actions workflow is heavily based on GitHub's mixed-party [starter workflows]. A copy of their MIT License is available in [actions/starter-workflows]. - ----- - -[^1]: [It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll#creating-your-site). - -[Jekyll]: https://jekyllrb.com -[Just the Docs]: https://just-the-docs.github.io/just-the-docs/ -[GitHub Pages]: https://docs.github.com/en/pages -[GitHub Pages / Actions workflow]: https://github.blog/changelog/2022-07-27-github-pages-custom-github-actions-workflows-beta/ -[Bundler]: https://bundler.io -[use this template]: https://github.com/just-the-docs/just-the-docs-template/generate -[`jekyll-default-layout`]: https://github.com/benbalter/jekyll-default-layout -[`jekyll-seo-tag`]: https://jekyll.github.io/jekyll-seo-tag -[MIT License]: https://en.wikipedia.org/wiki/MIT_License -[starter workflows]: https://github.com/actions/starter-workflows/blob/main/pages/jekyll.yml -[actions/starter-workflows]: https://github.com/actions/starter-workflows/blob/main/LICENSE diff --git a/doc/_config.yml b/doc/_config.yml index 65f8708..abd5948 100644 --- a/doc/_config.yml +++ b/doc/_config.yml @@ -5,4 +5,4 @@ theme: just-the-docs url: https://wanxp.github.io/obsidian-douban aux_links: # remove if you don't want this link to appear on your pages - Template Repository: https://github.com/Wanxp/obsidian-douban + Github Repository: https://github.com/Wanxp/obsidian-douban diff --git a/doc/index.md b/doc/index.md deleted file mode 100644 index ca0c545..0000000 --- a/doc/index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Home -layout: home ---- - -This is a *bare-minimum* template to create a Jekyll site that uses the [Just the Docs] theme. You can easily set the created site to be published on [GitHub Pages] – the [README] file explains how to do that, along with other details. - -If [Jekyll] is installed on your computer, you can also build and preview the created site *locally*. This lets you test changes before committing them, and avoids waiting for GitHub Pages.[^1] And you will be able to deploy your local build to a different platform than GitHub Pages. - -More specifically, the created site: - -- uses a gem-based approach, i.e. uses a `Gemfile` and loads the `just-the-docs` gem -- uses the [GitHub Pages / Actions workflow] to build and publish the site on GitHub Pages - -Other than that, you're free to customize sites that you create with this template, however you like. You can easily change the versions of `just-the-docs` and Jekyll it uses, as well as adding further plugins. - -[Browse our documentation][Just the Docs] to learn more about how to use this theme. - -To get started with creating a site, simply: - -1. click "[use this template]" to create a GitHub repository -2. go to Settings > Pages > Build and deployment > Source, and select GitHub Actions - -If you want to maintain your docs in the `docs` directory of an existing project repo, see [Hosting your docs from an existing project repo](https://github.com/just-the-docs/just-the-docs-template/blob/main/README.md#hosting-your-docs-from-an-existing-project-repo) in the template README. - ----- - -[^1]: [It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll#creating-your-site). - -[Just the Docs]: https://just-the-docs.github.io/just-the-docs/ -[GitHub Pages]: https://docs.github.com/en/pages -[README]: https://github.com/just-the-docs/just-the-docs-template/blob/main/README.md -[Jekyll]: https://jekyllrb.com -[GitHub Pages / Actions workflow]: https://github.blog/changelog/2022-07-27-github-pages-custom-github-actions-workflows-beta/ -[use this template]: https://github.com/just-the-docs/just-the-docs-template/generate