Skip to content

Commit 6e6d17e

Browse files
jacobmllr95jacobmllr95
authored
docs: improve code examples and enhance wording (closes #4859) (#4882)
* Make `Bootstrap` always start with a capital `B` * Update nuxt.config.js * feat(docs): improve code examples * fix(docs): improve wording on `custom.scss` file
1 parent bda2a04 commit 6e6d17e

File tree

10 files changed

+102
-65
lines changed

10 files changed

+102
-65
lines changed

‎CHANGELOG.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -272,7 +272,7 @@ Released: 2020-01-08
272272
- **b-collapse:** add optional scoping to default slot
273273
([#4405](https://github.com/bootstrap-vue/bootstrap-vue/issues/4405))
274274
([8e95bac](https://github.com/bootstrap-vue/bootstrap-vue/commit/8e95bacf9d00562f2676689d067ae0db009cbbb6))
275-
- **b-container:** add support for bootstrap v4.4.x new responsive containers
275+
- **b-container:** add support for Bootstrap v4.4.x new responsive containers
276276
([0e318f4](https://github.com/bootstrap-vue/bootstrap-vue/commit/0e318f4755e65eb569dcc579938d0d72c02abd62))
277277
- **b-dropdown:** add splitClass property to dropdown component
278278
([#4394](https://github.com/bootstrap-vue/bootstrap-vue/issues/4394))
@@ -1932,7 +1932,7 @@ Released: 2019-02-18
19321932
([#2597](https://github.com/bootstrap-vue/bootstrap-vue/issues/2597))
19331933
([#2608](https://github.com/bootstrap-vue/bootstrap-vue/issues/2608))
19341934
([11c7524](https://github.com/bootstrap-vue/bootstrap-vue/commit/11c7524))
1935-
- **nuxt plugin:** fix typo with bootstrap vue css import properties
1935+
- **nuxt plugin:** fix typo with Bootstrap vue css import properties
19361936
([#2618](https://github.com/bootstrap-vue/bootstrap-vue/issues/2618))
19371937
([8581090](https://github.com/bootstrap-vue/bootstrap-vue/commit/8581090))
19381938
- **utils/get:** handle case where passed object is undefined
@@ -2011,7 +2011,7 @@ Released: (2019-02-14)
20112011
- **dependencies:** replace opencollective with opencollective-postinstall
20122012
([#2067](https://github.com/bootstrap-vue/bootstrap-vue/issues/2067))
20132013
([fa26882](https://github.com/bootstrap-vue/bootstrap-vue/commit/fa26882))
2014-
- **docs:** Update links to bootstrap v4.3 docs
2014+
- **docs:** Update links to Bootstrap v4.3 docs
20152015
([b5d5499](https://github.com/bootstrap-vue/bootstrap-vue/commit/b5d5499))
20162016
- **docs:** Button - fix typo ([#1962](https://github.com/bootstrap-vue/bootstrap-vue/issues/1962))
20172017
([dcbfcf9](https://github.com/bootstrap-vue/bootstrap-vue/commit/dcbfcf9))
@@ -2108,7 +2108,7 @@ Released: (2019-02-14)
21082108
[#1841](https://github.com/bootstrap-vue/bootstrap-vue/issues/1841)
21092109
([#2174](https://github.com/bootstrap-vue/bootstrap-vue/issues/2174))
21102110
([aacc7c0](https://github.com/bootstrap-vue/bootstrap-vue/commit/aacc7c0))
2111-
- **form-control:** remove interim class fixes from bootstrap 4.0.x
2111+
- **form-control:** remove interim class fixes from Bootstrap 4.0.x
21122112
([#1896](https://github.com/bootstrap-vue/bootstrap-vue/issues/1896))
21132113
([#2265](https://github.com/bootstrap-vue/bootstrap-vue/issues/2265))
21142114
([64bdf69](https://github.com/bootstrap-vue/bootstrap-vue/commit/64bdf69))

‎docs/assets/scss/styles.scss

Lines changed: 40 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,6 @@
1414

1515
.hljs {
1616
overflow-x: auto;
17-
position: relative;
1817
background-color: #f9f9f9;
1918
box-shadow: 0 1px 1px rgba(0, 0, 0, 0.125);
2019
}
@@ -137,42 +136,52 @@
137136
background-color: #eee;
138137
}
139138

140-
pre.editable {
141-
&::after {
142-
content: "(double click to edit)";
143-
position: absolute;
144-
top: 0;
145-
right: 0;
146-
color: #aaa;
147-
text-align: right;
148-
font-size: 0.75em;
149-
padding: 5px 10px 0;
150-
line-height: 15px;
151-
height: 15px;
152-
font-weight: 600;
153-
}
139+
.bd-code {
140+
position: relative;
154141

155-
&:hover {
142+
pre {
156143
&::after {
157-
font-size: 0.9em;
158-
color: #444;
159-
cursor: pointer;
144+
content: attr(data-filename);
145+
position: absolute;
146+
top: -7.5px;
147+
right: 0;
148+
color: #6c757d;
149+
text-align: right;
150+
font-size: 0.75em;
151+
line-height: 15px;
152+
font-weight: 600;
160153
}
161-
}
162154

163-
&.live {
164-
&::after {
165-
content: "Live";
166-
}
167-
}
155+
&.editable {
156+
&::after {
157+
content: "(Double click to edit)";
158+
top: 5px;
159+
right: 10px;
160+
}
168161

169-
&.error {
170-
border: 1px solid #dc3545;
171-
box-shadow: 0 1px 1px rgba(220, 53, 69, 0.5);
162+
&:hover {
163+
&::after {
164+
font-size: 0.85em;
165+
color: inherit;
166+
cursor: pointer;
167+
}
168+
}
172169

173-
&::after {
174-
content: "JavaScript compile error!";
175-
color: #dc3545;
170+
&.live {
171+
&::after {
172+
content: "Live";
173+
}
174+
}
175+
176+
&.error {
177+
border: 1px solid #dc3545;
178+
box-shadow: 0 1px 1px rgba(220, 53, 69, 0.5);
179+
180+
&::after {
181+
content: "JavaScript compile error!";
182+
color: #dc3545;
183+
}
184+
}
176185
}
177186
}
178187
}

‎docs/markdown/intro/README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -145,15 +145,15 @@ import 'bootstrap/dist/css/bootstrap.css'
145145
import 'bootstrap-vue/dist/bootstrap-vue.css'
146146
```
147147

148-
Or import Bootstrap and BootstrapVue `scss` files via a single custom SCSS file:
148+
**Alternatively** you can import Bootstrap and BootstrapVue `scss` files in a custom SCSS file:
149149

150150
```scss
151151
// custom.scss
152152
@import 'node_modules/bootstrap/scss/bootstrap';
153153
@import 'node_modules/bootstrap-vue/src/index.scss';
154154
```
155155

156-
Finally import the `custom.scss` file in your app entry point:
156+
Make sure to import the `custom.scss` file in your app entry point:
157157

158158
```js
159159
// app.js

‎docs/nuxt.config.js

Lines changed: 38 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -7,18 +7,21 @@ const hljs = require('highlight.js/lib/highlight.js')
77
hljs.registerLanguage('javascript', require('highlight.js/lib/languages/javascript'))
88
hljs.registerLanguage('typescript', require('highlight.js/lib/languages/typescript'))
99
hljs.registerLanguage('json', require('highlight.js/lib/languages/json'))
10-
hljs.registerLanguage('xml', require('highlight.js/lib/languages/xml')) // includes HTML
10+
hljs.registerLanguage('xml', require('highlight.js/lib/languages/xml')) // Includes HTML
1111
hljs.registerLanguage('css', require('highlight.js/lib/languages/css'))
1212
hljs.registerLanguage('scss', require('highlight.js/lib/languages/scss'))
13-
hljs.registerLanguage('bash', require('highlight.js/lib/languages/bash')) // includes sh
13+
hljs.registerLanguage('bash', require('highlight.js/lib/languages/bash')) // Includes sh
1414
hljs.registerLanguage('shell', require('highlight.js/lib/languages/shell'))
1515
hljs.registerLanguage('plaintext', require('highlight.js/lib/languages/plaintext'))
1616

17-
// Create a new marked renderer
18-
const renderer = new marked.Renderer()
17+
// --- Constants ---
18+
19+
const RX_CODE_FILENAME = /^\/\/ ([\w,\s-]+\.[A-Za-z]{1,4})\n/m
1920

2021
const ANCHOR_LINK_HEADING_LEVELS = [2, 3, 4, 5]
2122

23+
// --- Utility methods ---
24+
2225
// Get routes by a given dir
2326
const getRoutesByDir = (root, dir, excludes = []) =>
2427
fs
@@ -27,20 +30,42 @@ const getRoutesByDir = (root, dir, excludes = []) =>
2730
.filter(c => !/\.(s?css|js|ts)$/.test(c))
2831
.map(page => `/docs/${dir}/${page}`)
2932

33+
// --- Custom renderer ---
34+
35+
// Create a new marked renderer
36+
const renderer = new marked.Renderer()
37+
3038
// Custom "highlight.js" implementation for markdown renderer
3139
renderer.code = (code, language) => {
40+
const attrs = {
41+
class: `hljs ${language} p-2`,
42+
translate: 'no'
43+
}
44+
45+
const [, filename] = RX_CODE_FILENAME.exec(code) || []
46+
if (filename) {
47+
attrs['data-filename'] = filename
48+
code = code.replace(RX_CODE_FILENAME, '')
49+
}
50+
3251
const validLang = !!(language && hljs.getLanguage(language))
3352
const highlighted = validLang ? hljs.highlight(language, code).value : code
34-
return `<pre class="hljs ${language} text-monospace p-2 notranslate" translate="no">${highlighted}</pre>`
53+
54+
const attrsMarkup = Object.keys(attrs).reduce(
55+
(markup, attr) => `${markup}${markup ? ' ' : ''}${attr}="${attrs[attr]}"`,
56+
''
57+
)
58+
59+
return `<div class="bd-code"><pre ${attrsMarkup}>${highlighted}</pre></div>`
3560
}
3661

37-
// Instruct google translate not to translate `<code>` content, and
38-
// don't let browsers wrap the contents across lines
39-
renderer.codespan = text => {
40-
return `<code translate="no" class="notranslate text-nowrap">${text}</code>`
62+
// Instruct Google Translate not to translate `<code>` content
63+
// and don't let browsers wrap the contents across lines
64+
renderer.codespan = code => {
65+
return `<code class="text-nowrap" translate="no">${code}</code>`
4166
}
4267

43-
// Custom link renderer, to update bootstrap docs version in href
68+
// Custom link renderer, to update Bootstrap docs version in href
4469
// Only applies to markdown links (not explicit `<a href="..">...</a>` tags
4570
renderer.link = (href, title, text) => {
4671
let target = ''
@@ -92,7 +117,7 @@ renderer.heading = function(text, level, raw, slugger) {
92117
return `<h${level} ${attrs}>${getTextMarkup(text + anchor)}</h${level}>\n`
93118
}
94119

95-
// Convert lead-in blockquote paragraphs to true bootstrap docs leads
120+
// Convert lead-in blockquote paragraphs to true Bootstrap docs leads
96121
renderer.blockquote = function(text) {
97122
return text.replace('<p>', '<p class="bd-lead">')
98123
}
@@ -107,6 +132,8 @@ renderer.table = function() {
107132
return `<div class="table-responsive-sm">${table}</div>`
108133
}
109134

135+
// --- Main export ---
136+
110137
module.exports = {
111138
srcDir: __dirname,
112139

‎docs/plugins/play.js

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,10 @@ import hljs from '../utils/hljs'
55

66
// --- Constants ---
77

8-
const NAME_REGEX = /<!-- (.*)\.vue -->/
9-
const NAME_DEFINITION_REGEX = /<!-- .*\.vue -->/
10-
const TEMPLATE_REGEX = /<template>([\s\S]*)<\/template>/
11-
const SCRIPT_REGEX = /<script>([\s\S]*)<\/script>/
8+
const RX_NAME = /<!-- (.*)\.vue -->/
9+
const RX_NAME_DEFINITION = /<!-- .*\.vue -->/
10+
const RX_TEMPLATE = /<template>([\s\S]*)<\/template>/
11+
const RX_SCRIPT = /<script>([\s\S]*)<\/script>/
1212

1313
const CLASS_NAMES = {
1414
editable: 'editable',
@@ -25,8 +25,8 @@ const match = (regex, text) => (regex.exec(text) || [])[1]
2525
const removeNode = node => node && node.parentNode && node.parentNode.removeChild(node)
2626

2727
const parseVueTemplate = text => {
28-
let template = match(TEMPLATE_REGEX, text)
29-
const script = match(SCRIPT_REGEX, text)
28+
let template = match(RX_TEMPLATE, text)
29+
const script = match(RX_SCRIPT, text)
3030
const options = {}
3131

3232
// It is plain code
@@ -58,15 +58,16 @@ const createVM = (name, node, vnode) => {
5858

5959
const { template, options } = vt
6060

61-
// Create a placeholder after node
61+
// Create a placeholder after node container
62+
const container = node.parentNode
6263
const holder = document.createElement('div')
63-
node.parentNode.insertBefore(holder, node)
64+
container.parentNode.insertBefore(holder, container)
6465

6566
// Create VM
6667
return new Vue({
6768
...options,
6869
el: holder,
69-
template: `<div class="bd-example vue-example vue-example-${name} notranslate" translate="no">${template}</div>`,
70+
template: `<div class="bd-example vue-example vue-example-${name}" translate="no">${template}</div>`,
7071
router: vnode.context.$router
7172
})
7273
} catch (e) {
@@ -96,20 +97,20 @@ const processExamples = (el, binding, vnode) => {
9697
}
9798

9899
// Get all code-snippets
99-
const pres = [...el.querySelectorAll('pre.hljs')]
100+
const pres = [...el.querySelectorAll('.bd-code pre')]
100101

101102
// Iterate over them and parse
102103
pres.forEach(pre => {
103104
// Store example name globally
104-
const name = match(NAME_REGEX, pre.textContent)
105+
const name = match(RX_NAME, pre.textContent)
105106

106107
// Exit early when no name is given
107108
if (!name) {
108109
return
109110
}
110111

111112
// Remove name definition
112-
const text = pre.textContent.replace(NAME_DEFINITION_REGEX, '').trim()
113+
const text = pre.textContent.replace(RX_NAME_DEFINITION, '').trim()
113114
pre.textContent = text
114115

115116
// Highlight again

‎src/components/form-checkbox/_form-checkbox.scss

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Adds control sizing to bootstrap custom checkbox/switch inputs
1+
// Adds control sizing to Bootstrap custom checkbox/switch inputs
22

33
.custom-checkbox.b-custom-control-lg,
44
.input-group-lg .custom-checkbox {

‎src/components/form-input/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -582,7 +582,7 @@ these methods and properties. Support will vary based on input type.
582582

583583
## Using HTML5 `<input>` as an alternative
584584

585-
If you just need a simple input with basic bootstrap styling, you can simply use the following:
585+
If you just need a simple input with basic Bootstrap styling, you can simply use the following:
586586

587587
```html
588588
<template>

‎src/components/form-radio/_form-radio.scss

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Adds control sizing to bootstrap custom radio inputs
1+
// Adds control sizing to Bootstrap custom radio inputs
22

33
.custom-radio.b-custom-control-lg,
44
.input-group-lg .custom-radio {

‎src/components/table/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1567,7 +1567,7 @@ will be using other means to convey that a row is selected (such as a scoped fie
15671567
example).
15681568

15691569
The `selected-variant` can be any of the
1570-
[standard (or custom) bootstrap base color variants](/docs/reference/color-variants), or the special
1570+
[standard (or custom) Bootstrap base color variants](/docs/reference/color-variants), or the special
15711571
[table `active` variant](/docs/reference/color-variants#table-variants) (the default) which takes
15721572
precedence over any specific row or cell variants.
15731573

‎src/icons/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -192,7 +192,7 @@ unless you are using the `IconsPlugin` or `BootstrapVueIcons` plugin.
192192
## Variants
193193

194194
By default, icons inherit the current text color of their parent element. All icon components
195-
provide a `variant` prop to apply one of the bootstrap contextual text variant colors:
195+
provide a `variant` prop to apply one of the Bootstrap contextual text variant colors:
196196

197197
```html
198198
<template>

0 commit comments

Comments
 (0)