Skip to content

Commit ce86da7

Browse files
yyx990803yyx990803
committed
theme tweaks
1 parent f97e676 commit ce86da7

File tree

10 files changed

+247
-137
lines changed

10 files changed

+247
-137
lines changed

Diff for: ‎docs/assets.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Asset Handling
2+
3+
## Relative URLs
4+
5+
Since your markdown files are compiled into Vue components via webpack, you can safely reference any asset using relative paths on your file system:
6+
7+
``` markdown
8+
![logo][./logo.png]
9+
```
10+
11+
This would work the same way as if you are referencing it inside a `*.vue` file template. The image will be processed with `url-loader` and `file-loader`, and copied to appropriate locations in the generated static build.
12+
13+
## Public Files
14+
15+
Sometimes you may need to provide some static assets that are not directly referenced in any of your markdown or theme components - for example, favicons and PWA icons. In that case you can put them inside `.vuepress/public` and they will be copied to the root of the generated static build.
16+
17+
## Referencing Base URL Dynamically
18+
19+
If your site is deployed to a non-root URL, you will need to set the `base` option in `.vuepress/config.js`. The value of this option will be available anywhere in markdown or your components as `$site.base`. In order to use it though, you will have to use direct HTML along with Vue bindings:
20+
21+
``` html
22+
<img :src="$site.base + 'foo.png'" alt="foo">
23+
```

Diff for: ‎docs/markdown.md

+43-1
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,31 @@
1313

1414
Headers automatically get anchor links applied.
1515

16+
## YAML Front Matter
17+
18+
[YAML front matter](https://jekyllrb.com/docs/frontmatter/) is supported out of the box:
19+
20+
```
21+
---
22+
title: Blogging Like a Hacker
23+
lang: en-US
24+
---
25+
```
26+
27+
The data will be available to the rest of the page, plus all custom and theming components as `$page`.
28+
29+
`title` and `lang` will be automatically set on the current page. In addition you can specify extra meta tags to be injected:
30+
31+
```
32+
---
33+
meta:
34+
- name: description
35+
content: hello
36+
- name: keywords
37+
content: super duper SEO
38+
---
39+
```
40+
1641
## Table of Contents
1742

1843
**Input**
@@ -97,4 +122,21 @@ export default {
97122

98123
:tada: :100:
99124

100-
## Custom Configuration
125+
## Advanced Configuration
126+
127+
VuePress uses [markdown-it]() as the markdown renderer. A lot of the extensions above are implemented via custom plugins. You can further customize the `markdown-it` instance using the `markdown` option in `.vuepress/config.js`:
128+
129+
``` js
130+
module.exports = {
131+
markdown: {
132+
// options for markdown-it-anchor
133+
anchor: { permalink: false },
134+
// options for markdown-it-toc
135+
toc: { includeLevel: [1, 2] },
136+
config: md => {
137+
// use more markdown-it plugins!
138+
md.use(require('markdown-it-xxx'))
139+
}
140+
}
141+
}
142+
```

Diff for: ‎docs/theming.md

+57-5
Original file line numberDiff line numberDiff line change
@@ -9,16 +9,68 @@ VuePress uses Vue single file components for custom themes. To use a custom layo
99
      └── Layout.vue
1010
```
1111

12-
From there it's the same as developing a normal Vue application. There are only a few special things to note:
12+
From there it's the same as developing a normal Vue application. It is entirely up to you how to organize your theme.
13+
14+
## Using Theme from a Dependency
15+
16+
Themes can be published on npm as `vuepress-theme-xxx`.
17+
18+
To use a theme from an npm dependency, provide a `theme` option in `.vuepress/config.js`:
19+
20+
``` js
21+
module.exports = {
22+
theme: 'awesome'
23+
}
24+
```
25+
26+
VuePress will attempt to locate and use `node_modules/vuepress-theme-awesome/Layout.vue`.
27+
28+
## Content Outlet
29+
30+
The compiled content of the current `.md` file being rendered will be available as a special `<Content/>` global component. You will need to render it somewhere in your layout in order to display the content of the page. The simplest theme can be just a single `Layout.vue` component with the following content:
31+
32+
``` html
33+
<template>
34+
<div class="theme-container">
35+
<Content/>
36+
</div>
37+
</template>
38+
```
39+
40+
In addition to rendering the markdown content, the `<Content/>` component is also responsible for setting the title and other metadata of a specific page.
1341

1442
## Site and Page Metadata
1543

1644
The `Layout` component will be invoked once for every `.md` file in `docs`, and the metadata for the entire site and that specific page will be exposed respectively in `$site` and `$page` properties which are injected into every component in the app.
1745

18-
// TODO details about $site & $page
46+
This is the value of `$site` of this very website:
1947

20-
## Content Outlet
48+
``` json
49+
{
50+
"title": "VuePress",
51+
"description": "Minimalistic docs generator with Vue component based layout system",
52+
"base": "/vuepress/",
53+
"pages": [
54+
{
55+
"path": "/",
56+
"title": "VuePress",
57+
"frontmatter": {}
58+
},
59+
...
60+
]
61+
}
62+
```
63+
64+
`title`, `description` and `base` are copied from respective fields in `.vuepress/config.js`. `pages` contains an array of metadata objects for each page, including its path, page title (explicitly specified in YAML frontmatter or inferred from the first header on the page), and any YAML frontmatter data in that file.
2165

22-
The compiled content of the current `.md` file being rendered will be available as a special `<Content/>` global component. You will need to render it somewhere in your layout in order to display the content of the page.
66+
This is the `$page` object for this page you are looking at:
67+
68+
``` json
69+
{
70+
"path": "/theming.html",
71+
"title": "Custom Theme",
72+
"frontmatter": {}
73+
}
74+
```
2375

24-
// TODO give an example
76+
If the user provided `themeConfig` in `.vuepress/config.js`, it will also be available as `$site.themeConfig`. You can use this to allow users to customize behavior of your theme - for example, specifying categories and page order. You can then use these data together with `$site.pages` to dynamically construct navigation links.

Diff for: ‎lib/default-theme/Layout.vue

+2-1
Original file line numberDiff line numberDiff line change
@@ -34,5 +34,6 @@ export default {
3434
}
3535
</script>
3636

37+
<style src="./nprogress.css"></style>
3738
<style src="prismjs/themes/prism-tomorrow.css"></style>
38-
<style src="./styles.css"></style>
39+
<style src="./theme.stylus" lang="stylus"></style>

Diff for: ‎lib/default-theme/styles.css

-126
This file was deleted.

Diff for: ‎lib/default-theme/theme.stylus

+55
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
.theme-container
2+
font-family -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif
3+
padding 0 30px
4+
5+
a
6+
color #41b883
7+
text-decoration none
8+
9+
h1, h2, h3, h4, h5, h6
10+
&:hover .header-anchor
11+
opacity: 1
12+
13+
a.header-anchor
14+
font-size 0.8em
15+
float left
16+
padding-right 4px
17+
margin-left -20px
18+
margin-top 3px
19+
opacity 0
20+
21+
pre, pre[class*="language-"]
22+
background-color #2d2d2d
23+
color white
24+
line-height 1.4
25+
border-radius 5px
26+
padding 1.3rem 1.575rem
27+
white-space pre-wrap
28+
word-break break-word
29+
overflow auto
30+
code
31+
font-family source-code-pro, Menlo, Monaco, Consolas, "Courier New", monospace
32+
font-size 14px
33+
-webkit-font-smoothing antialiased
34+
35+
.highlighted-line
36+
background-color #14161a
37+
display block
38+
margin 0 -1.575rem
39+
padding 0.2rem 1.575rem 0
40+
41+
div
42+
&.tip
43+
color white
44+
background-color green
45+
&.warning
46+
background-color yellow
47+
&.danger
48+
color white
49+
background-color red
50+
51+
p
52+
&.demo
53+
padding 1rem
54+
border 1px solid #ddd
55+
border-radius 4px

Diff for: ‎lib/markdown/index.js

+7-2
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,13 @@ module.exports = ({ markdown = {}}) => {
2525
.use(hoistScriptStyle)
2626
// 3rd party plugins
2727
.use(emoji)
28-
.use(anchor, Object.assign({ permalink: true, permalinkBefore: true }, markdown.anchor))
29-
.use(toc, Object.assign({ includeLevel: [2, 3] }, markdown.toc))
28+
.use(anchor, Object.assign({
29+
permalink: true,
30+
permalinkBefore: true // TODO use an svg?
31+
}, markdown.anchor))
32+
.use(toc, Object.assign({
33+
includeLevel: [2, 3]
34+
}, markdown.toc))
3035
.use(container, 'tip')
3136
.use(container, 'warning')
3237
.use(container, 'danger')

Diff for: ‎lib/prepare.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ async function resolveOptions (sourceDir) {
8080
if (fs.existsSync(notFoundPath)) {
8181
options.notFoundPath = notFoundPath
8282
} else {
83-
throw new Error('[vuepress] Custom theme must have a NotFound.vue file.')
83+
options.notFoundPath = path.resolve(__dirname, 'default-theme/NotFound.vue')
8484
}
8585
}
8686

Diff for: ‎package.json

+2
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,8 @@
6868
"postcss-loader": "^2.1.3",
6969
"prismjs": "^1.13.0",
7070
"rimraf": "^2.6.2",
71+
"stylus": "^0.54.5",
72+
"stylus-loader": "^3.0.2",
7173
"url-loader": "^1.0.1",
7274
"vue": "^2.5.16",
7375
"vue-loader": "^15.0.0-rc.1",

0 commit comments

Comments
 (0)