diff --git a/docs/components/CreateValaxyTooltip.vue b/docs/components/CreateValaxyTooltip.vue new file mode 100644 index 00000000..4bbeb3a1 --- /dev/null +++ b/docs/components/CreateValaxyTooltip.vue @@ -0,0 +1,46 @@ + + + diff --git a/docs/pages/guide/best-pratice.md b/docs/pages/guide/best-pratice.md index 9562958b..5a3eb590 100644 --- a/docs/pages/guide/best-pratice.md +++ b/docs/pages/guide/best-pratice.md @@ -43,6 +43,7 @@ useScriptTag('//busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js') ``` 3. 如果文章中不想使用外链图片，建议按照以下格式创建文件夹及引用图片，便于管理和迁移。 + ```txt posts ├─ your-post @@ -57,8 +58,8 @@ posts ![](./a.png) ![](./b.png) ``` -::: +::: ::: en @@ -67,9 +68,10 @@ The following are some of our recommended best practices, but you do not need to 1. It is recommended to name folders and files in English. ```txt -blog/pages/posts/your-post. md +blog/pages/posts/your-post.md ``` -2. When inserting third-party/large amounts of dynamic content, priority should be given to encapsulating it as a component and placing it in `blog/components`, and introducing it through component tag names. + +2. When inserting third-party/large amounts of dynamic content, priority should be given to encapsulating it as a component and placing it in `blog/components`, and introducing it through component tag names. ```vue // blog/components/BszComponent.vue @@ -112,5 +114,4 @@ posts ![](./b.png) ``` - ::: diff --git a/docs/pages/guide/features.md b/docs/pages/guide/features.md index 16262f76..0120380f 100644 --- a/docs/pages/guide/features.md +++ b/docs/pages/guide/features.md @@ -148,6 +148,14 @@ All icon names added to `config.unocss.safelist` will be ready for hot reloading ### Syntax Highlighting {lang="en"} +::: en +> More info about syntax highlighting can be found at [Markdown Syntax Highlighting](/guide/markdown#syntax-highlighting). +::: + +::: zh-CN +> 更多关于代码高亮的信息请参见 [Markdown 代码高亮](/guide/markdown#%25E4%25BB%25A3%25E7%25A0%2581%25E8%25A1%258C%25E9%25AB%2598%25E4%25BA%25AE)。 +::: + ::: zh-CN 基于 [Shiki](https://github.com/shikijs/shiki) 实现。 Valaxy 支持 `vue` 等语法高亮，拷贝代码，高亮其中某一行。 diff --git a/docs/pages/guide/getting-started.md b/docs/pages/guide/getting-started.md index 6dce1064..cc200de8 100644 --- a/docs/pages/guide/getting-started.md +++ b/docs/pages/guide/getting-started.md @@ -119,10 +119,6 @@ If you are a Windows user, I strongly recommend using a Unix-like shell (such as -```bash -npm init valaxy -``` - ::: zh-CN > 由于 `npm init` 会缓存您此前下载的版本，我更推荐您使用 `pnpm` 来创建模版。 > 安装 [pnpm](https://pnpm.io/)：`npm i -g pnpm` @@ -133,22 +129,34 @@ npm init valaxy > Install [pnpm](https://pnpm.io/)：`npm i -g pnpm` ::: -```bash +::: code-group + +```bash [pnpm] pnpm create valaxy ``` +```bash [npm] +npm init valaxy +``` + +::: + +::: details You will be greeted with a few simple questions. + +::: + ::: zh-CN 跟随命令行提示完成创建！ > 默认使用主题 [valaxy-theme-yun](https://github.com/YunYouJun/valaxy/blob/main/packages/valaxy-theme-yun/)，当然您也可以安装使用任意其他主题。 -> 本文档同样是一个 Valaxy 主题 [valaxy-theme-press](https://github.com/YunYouJun/valaxy/blob/main/packages/valaxy-theme-press/)，它的灵感来自 VitePress。 +> 本文档同样是一个 Valaxy 主题 [valaxy-theme-press](https://github.com/YunYouJun/valaxy/blob/main/packages/valaxy-theme-press/)，它的灵感来自 [VitePress](https://vitepress.dev/)。 ::: ::: en Follow the prompt in the commandline to complete the process! > The default theme used is [valaxy-theme-yun](https://github.com/YunYouJun/valaxy/blob/main/packages/valaxy-theme-yun/), but you can also install any other themes. -> This documentation is also a Valaxy theme: [valaxy-theme-press](https://github.com/YunYouJun/valaxy/blob/main/packages/valaxy-theme-press/). +> This documentation is also a Valaxy theme: [valaxy-theme-press](https://github.com/YunYouJun/valaxy/blob/main/packages/valaxy-theme-press/). It is inspired by [VitePress](https://vitepress.dev/). ::: ## Usage {lang="en"} @@ -169,12 +177,20 @@ Follow the prompt in the commandline to complete the process! Install the dependencies: ::: -```bash +::: code-group + +```bash [pnpm] +# install +pnpm i +``` + +```bash [npm] # install npm i -# or pnpm i ``` +:::: + ::: zh-CN 启动预览： ::: @@ -183,12 +199,20 @@ npm i Start a preview: ::: -```bash +::: code-group + +```bash [pnpm] +# start +pnpm dev +``` + +```bash [npm] # start npm run dev -# or pnpm dev ``` +:::: + ::: zh-CN 博客创建完毕，查看本地 `http://localhost:4859/`，玩的开心！ @@ -235,7 +259,17 @@ See [Deployment](/guide/deploy) for deployment guide. ## 升级 {lang="zh-CN"} -```bash +::: code-group + +```bash [pnpm] +cd your-blog +# upgrade valaxy +pnpm add valaxy@latest +# upgrade theme +pnpm add valaxy-theme-yun@latest +``` + +```bash [npm] cd your-blog # upgrade valaxy npm i valaxy@latest @@ -243,6 +277,8 @@ npm i valaxy@latest npm i valaxy-theme-yun@latest ``` +::: + ### pnpm ::: zh-CN diff --git a/docs/pages/guide/markdown.md b/docs/pages/guide/markdown.md index c6ea6c33..7d563051 100644 --- a/docs/pages/guide/markdown.md +++ b/docs/pages/guide/markdown.md @@ -422,3 +422,79 @@ $$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$ | $\nabla \cdot \vec{\mathbf{B}} = 0$ | divergence of $\vec{\mathbf{B}}$ is zero | | $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} = \vec{\mathbf{0}}$ | curl of $\vec{\mathbf{E}}$ is proportional to the rate of change of $\vec{\mathbf{B}}$ | | $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _wha?_ | + +## Markdown File Inclusion + +**Input** + +```md +# Docs + +## Basics + + +``` + +**Part file** (`parts/basics.md`) + +```md +Some getting started stuff. + +### Configuration + +Can be created using `.foorc.json`. +``` + +**Equivalent code** + +```md +# Docs + +## Basics + +Some getting started stuff. + +### Configuration + +Can be created using `.foorc.json`. +``` + +It also supports selecting a line range: + +**Input** + +```md +# Docs + +## Basics + + +``` + +**Part file** (`parts/basics.md`) + +```md +Some getting started stuff. + +### Configuration + +Can be created using `.foorc.json`. +``` + +**Equivalent code** + +```md +# Docs + +## Basics + +### Configuration + +Can be created using `.foorc.json`. +``` + +The format of the selected line range can be: `{3,}`, `{,10}`, `{1,10}` + +::: warning +Note that this does not throw errors if your file is not present. Hence, when using this feature make sure that the contents are being rendered as expected. +::: diff --git a/docs/pages/guide/post.md b/docs/pages/guide/post.md index c539ed2e..ccdb58e6 100644 --- a/docs/pages/guide/post.md +++ b/docs/pages/guide/post.md @@ -46,11 +46,6 @@ hide: true - `hide`: 你可以在文章头部添加 hide 属性，来临时隐藏某篇文章。（该文章仍然会被渲染） - `true` / `all`: 当设置为 `true` 或 `all` 时，该文章仍然会被渲染，你可以直接访问链接进行查看。但不会被显示在展示的文章卡片与归档中。 - `index`: 设置为 `index` 时，将只在首页隐藏，归档中仍然展示。（譬如放一些没有必要放在首页的笔记，并在归档中方便自己查看。） -- `excerpt_type`: 预览列表**摘要**的渲染类型（与 `` 配合使用） - - `md`: 展示原始 Markdown - - `html`: 以 HTML 形式展示 - - `text`: 以纯文本形式展示（去除 HTML 标签） - ::: ::: en @@ -59,6 +54,31 @@ hide: true - `hide`: Adding `hide` in the header allows you to hide the article temporarily. (The article will still be rendered) - `true` / `all`: When set to `true` or `all`, the article will be rendered, and you can view it by visiting the link directly. It will not be displayed in article cards or archives. - `index`: When set to `index`, it will be hidden only in the front page. It will still be displayed in archives. (You can use this for some notes unnecessary for the front page, but good for the archive for reference sometimes) + + +::: + +## 摘要 {lang="zh-CN"} + +## Excerpt {lang="en"} + +::: zh-CN +你可以通过插入 `` 的方式生成摘要（excerpt）。 +可通过设置 `excerpt_type` 设置摘要渲染类型。 + +- `excerpt`: 自定义摘要（优先级高于 ``） +- `excerpt_type`: 预览列表**摘要**的渲染类型（与 `` 配合使用） + - `md`: 展示原始 Markdown + - `html`: 以 HTML 形式展示 + - `text`: 以纯文本形式展示（去除 HTML 标签） + +::: + +::: en +You can insert `` to generate an excerpt. +You can set the excerpt rendering type by setting `excerpt_type`. + +- `excerpt`: Custom excerpt (higher priority than ``) - `excerpt_type`: The rendering type for the excerpt in the preview list (Used with ``) - `md`: Display as original markdown - `html`: Display as HTML @@ -66,44 +86,86 @@ hide: true ::: -## 摘要 {lang="zh-CN"} +::: code-group -::: zh-CN -你可以通过插入 `` 的方式生成摘要（excerpt）。 -可通过设置 `excerpt_type` 设置摘要渲染类型。 - -```md +```md{3,10} [excerpt_type: text] --- -title: 嘿嘿嘿 +title: 'excerpt_type: text' excerpt_type: text --- -这里是摘要 +## Header + +![yun-bg](https://cdn.yunyoujun.cn/img/bg/stars-timing-0-blur-30px.jpg) -这里是正文 +Main Content +``` + +```md{3,10} [excerpt_type: md] +--- +title: 'excerpt_type: md' +excerpt_type: md +--- + +## Header + +![yun-bg](https://cdn.yunyoujun.cn/img/bg/stars-timing-0-blur-30px.jpg) + + + +Main Content +``` + +```md{3,10} [excerpt_type: html] +--- +title: 'excerpt_type: html' +excerpt_type: html +--- + +## Header + +![yun-bg](https://cdn.yunyoujun.cn/img/bg/stars-timing-0-blur-30px.jpg) + + + +Main Content +``` + +```md{3} [custom excerpt] +--- +title: 'custom excerpt' +excerpt: This is a custom excerpt. +--- + +## Header + +![yun-bg](https://cdn.yunyoujun.cn/img/bg/stars-timing-0-blur-30px.jpg) + +Main Content ``` ::: -## Excerpt {lang="en"} +You will get excerpt: -::: en -You can insert `` to generate an excerpt. -You can set the excerpt rendering type by setting `excerpt_type`. +::: code-group -```md ---- -title: Hello -excerpt_type: text ---- +```md [excerpt_type: text] +HEADER yun-bg +``` -This is the experpt +```md [excerpt_type: md] +## Header ![yun-bg](https://cdn.yunyoujun.cn/img/bg/stars-timing-0-blur-30px.jpg) +``` - +```md [excerpt_type: html] + +``` -Here goes the body +```md [custom excerpt] +This is a custom excerpt. ``` ::: diff --git a/packages/valaxy-theme-press/README.md b/packages/valaxy-theme-press/README.md index 4a7f88fc..3875740d 100644 --- a/packages/valaxy-theme-press/README.md +++ b/packages/valaxy-theme-press/README.md @@ -1,11 +1,11 @@ # valaxy-theme-press -This is a theme for valaxy docs. +This is a theme for [valaxy docs](https://valaxy.site/). Inspired by [vitepress](https://vitepress.dev). 我开发此主题以编写 Valaxy 的初期文档，同时以便发现 valaxy 编写主题中的痛点。 - +它增加了 VitePress 此前默认所没有的一些功能，KaTeX、文章分类、单页 CSS i18n + Vue i18n、Vue Router、Pinia 状态管理，组件自动注册等。 - [预览](https://press.valaxy.site) diff --git a/packages/valaxy-theme-press/client/config.ts b/packages/valaxy-theme-press/client/config.ts new file mode 100644 index 00000000..57bd2cad --- /dev/null +++ b/packages/valaxy-theme-press/client/config.ts @@ -0,0 +1 @@ +export const targetPadding = -40 diff --git a/packages/valaxy-theme-press/client/index.ts b/packages/valaxy-theme-press/client/index.ts index 3b54ff1a..4bcdb7ab 100644 --- a/packages/valaxy-theme-press/client/index.ts +++ b/packages/valaxy-theme-press/client/index.ts @@ -1 +1,3 @@ +export * from './config' + export * from '../composables' diff --git a/packages/valaxy-theme-press/components/ValaxyMain.vue b/packages/valaxy-theme-press/components/ValaxyMain.vue index 1b97e3b4..10adad0c 100644 --- a/packages/valaxy-theme-press/components/ValaxyMain.vue +++ b/packages/valaxy-theme-press/components/ValaxyMain.vue @@ -1,9 +1,11 @@