docs: improve code examples and enhance wording (closes #4859)

CHANGELOG.md

@@ -272,7 +272,7 @@ Released: 2020-01-08
 - **b-collapse:** add optional scoping to default slot
   ([#4405](https://github.com/bootstrap-vue/bootstrap-vue/issues/4405))
   ([8e95bac](https://github.com/bootstrap-vue/bootstrap-vue/commit/8e95bacf9d00562f2676689d067ae0db009cbbb6))
-- **b-container:** add support for bootstrap v4.4.x new responsive containers
+- **b-container:** add support for Bootstrap v4.4.x new responsive containers
   ([0e318f4](https://github.com/bootstrap-vue/bootstrap-vue/commit/0e318f4755e65eb569dcc579938d0d72c02abd62))
 - **b-dropdown:** add splitClass property to dropdown component
   ([#4394](https://github.com/bootstrap-vue/bootstrap-vue/issues/4394))
@@ -1932,7 +1932,7 @@ Released: 2019-02-18
   ([#2597](https://github.com/bootstrap-vue/bootstrap-vue/issues/2597))
   ([#2608](https://github.com/bootstrap-vue/bootstrap-vue/issues/2608))
   ([11c7524](https://github.com/bootstrap-vue/bootstrap-vue/commit/11c7524))
-- **nuxt plugin:** fix typo with bootstrap vue css import properties
+- **nuxt plugin:** fix typo with Bootstrap vue css import properties
   ([#2618](https://github.com/bootstrap-vue/bootstrap-vue/issues/2618))
   ([8581090](https://github.com/bootstrap-vue/bootstrap-vue/commit/8581090))
 - **utils/get:** handle case where passed object is undefined
@@ -2011,7 +2011,7 @@ Released: (2019-02-14)
 - **dependencies:** replace opencollective with opencollective-postinstall
   ([#2067](https://github.com/bootstrap-vue/bootstrap-vue/issues/2067))
   ([fa26882](https://github.com/bootstrap-vue/bootstrap-vue/commit/fa26882))
-- **docs:** Update links to bootstrap v4.3 docs
+- **docs:** Update links to Bootstrap v4.3 docs
   ([b5d5499](https://github.com/bootstrap-vue/bootstrap-vue/commit/b5d5499))
 - **docs:** Button - fix typo ([#1962](https://github.com/bootstrap-vue/bootstrap-vue/issues/1962))
   ([dcbfcf9](https://github.com/bootstrap-vue/bootstrap-vue/commit/dcbfcf9))
@@ -2108,7 +2108,7 @@ Released: (2019-02-14)
   [#1841](https://github.com/bootstrap-vue/bootstrap-vue/issues/1841)
   ([#2174](https://github.com/bootstrap-vue/bootstrap-vue/issues/2174))
   ([aacc7c0](https://github.com/bootstrap-vue/bootstrap-vue/commit/aacc7c0))
-- **form-control:** remove interim class fixes from bootstrap 4.0.x
+- **form-control:** remove interim class fixes from Bootstrap 4.0.x
   ([#1896](https://github.com/bootstrap-vue/bootstrap-vue/issues/1896))
   ([#2265](https://github.com/bootstrap-vue/bootstrap-vue/issues/2265))
   ([64bdf69](https://github.com/bootstrap-vue/bootstrap-vue/commit/64bdf69))

docs/assets/scss/styles.scss

@@ -14,7 +14,6 @@
 
 .hljs {
   overflow-x: auto;
-  position: relative;
   background-color: #f9f9f9;
   box-shadow: 0 1px 1px rgba(0, 0, 0, 0.125);
 }
@@ -137,42 +136,52 @@
   background-color: #eee;
 }
 
-pre.editable {
-  &::after {
-    content: "(double click to edit)";
-    position: absolute;
-    top: 0;
-    right: 0;
-    color: #aaa;
-    text-align: right;
-    font-size: 0.75em;
-    padding: 5px 10px 0;
-    line-height: 15px;
-    height: 15px;
-    font-weight: 600;
-  }
+.bd-code {
+  position: relative;
 
-  &:hover {
+  pre {
     &::after {
-      font-size: 0.9em;
-      color: #444;
-      cursor: pointer;
+      content: attr(data-filename);
+      position: absolute;
+      top: -7.5px;
+      right: 0;
+      color: #6c757d;
+      text-align: right;
+      font-size: 0.75em;
+      line-height: 15px;
+      font-weight: 600;
     }
-  }
 
-  &.live {
-    &::after {
-      content: "Live";
-    }
-  }
+    &.editable {
+      &::after {
+        content: "(Double click to edit)";
+        top: 5px;
+        right: 10px;
+      }
 
-  &.error {
-    border: 1px solid #dc3545;
-    box-shadow: 0 1px 1px rgba(220, 53, 69, 0.5);
+      &:hover {
+        &::after {
+          font-size: 0.85em;
+          color: inherit;
+          cursor: pointer;
+        }
+      }
 
-    &::after {
-      content: "JavaScript compile error!";
-      color: #dc3545;
+      &.live {
+        &::after {
+          content: "Live";
+        }
+      }
+
+      &.error {
+        border: 1px solid #dc3545;
+        box-shadow: 0 1px 1px rgba(220, 53, 69, 0.5);
+
+        &::after {
+          content: "JavaScript compile error!";
+          color: #dc3545;
+        }
+      }
     }
   }
 }

docs/markdown/intro/README.md

@@ -145,15 +145,15 @@ import 'bootstrap/dist/css/bootstrap.css'
 import 'bootstrap-vue/dist/bootstrap-vue.css'
 ```
 
-Or import Bootstrap and BootstrapVue `scss` files via a single custom SCSS file:
+**Alternatively** you can import Bootstrap and BootstrapVue `scss` files in a custom SCSS file:
 
 ```scss
 // custom.scss
 @import 'node_modules/bootstrap/scss/bootstrap';
 @import 'node_modules/bootstrap-vue/src/index.scss';
 ```
 
-Finally import the `custom.scss` file in your app entry point:
+Make sure to import the `custom.scss` file in your app entry point:
 
 ```js
 // app.js

docs/nuxt.config.js

@@ -7,18 +7,21 @@ const hljs = require('highlight.js/lib/highlight.js')
 hljs.registerLanguage('javascript', require('highlight.js/lib/languages/javascript'))
 hljs.registerLanguage('typescript', require('highlight.js/lib/languages/typescript'))
 hljs.registerLanguage('json', require('highlight.js/lib/languages/json'))
-hljs.registerLanguage('xml', require('highlight.js/lib/languages/xml')) // includes HTML
+hljs.registerLanguage('xml', require('highlight.js/lib/languages/xml')) // Includes HTML
 hljs.registerLanguage('css', require('highlight.js/lib/languages/css'))
 hljs.registerLanguage('scss', require('highlight.js/lib/languages/scss'))
-hljs.registerLanguage('bash', require('highlight.js/lib/languages/bash')) // includes sh
+hljs.registerLanguage('bash', require('highlight.js/lib/languages/bash')) // Includes sh
 hljs.registerLanguage('shell', require('highlight.js/lib/languages/shell'))
 hljs.registerLanguage('plaintext', require('highlight.js/lib/languages/plaintext'))
 
-// Create a new marked renderer
-const renderer = new marked.Renderer()
+// --- Constants ---
+
+const RX_CODE_FILENAME = /^\/\/ ([\w,\s-]+\.[A-Za-z]{1,4})\n/m
 
 const ANCHOR_LINK_HEADING_LEVELS = [2, 3, 4, 5]
 
+// --- Utility methods ---
+
 // Get routes by a given dir
 const getRoutesByDir = (root, dir, excludes = []) =>
   fs
@@ -27,20 +30,42 @@ const getRoutesByDir = (root, dir, excludes = []) =>
     .filter(c => !/\.(s?css|js|ts)$/.test(c))
     .map(page => `/docs/${dir}/${page}`)
 
+// --- Custom renderer ---
+
+// Create a new marked renderer
+const renderer = new marked.Renderer()
+
 // Custom "highlight.js" implementation for markdown renderer
 renderer.code = (code, language) => {
+  const attrs = {
+    class: `hljs ${language} p-2`,
+    translate: 'no'
+  }
+
+  const [, filename] = RX_CODE_FILENAME.exec(code) || []
+  if (filename) {
+    attrs['data-filename'] = filename
+    code = code.replace(RX_CODE_FILENAME, '')
+  }
+
   const validLang = !!(language && hljs.getLanguage(language))
   const highlighted = validLang ? hljs.highlight(language, code).value : code
-  return `<pre class="hljs ${language} text-monospace p-2 notranslate" translate="no">${highlighted}</pre>`
+
+  const attrsMarkup = Object.keys(attrs).reduce(
+    (markup, attr) => `${markup}${markup ? ' ' : ''}${attr}="${attrs[attr]}"`,
+    ''
+  )
+
+  return `<div class="bd-code"><pre ${attrsMarkup}>${highlighted}</pre></div>`
 }
 
-// Instruct google translate not to translate `<code>` content, and
-// don't let browsers wrap the contents across lines
-renderer.codespan = text => {
-  return `<code translate="no" class="notranslate text-nowrap">${text}</code>`
+// Instruct Google Translate not to translate `<code>` content
+// and don't let browsers wrap the contents across lines
+renderer.codespan = code => {
+  return `<code class="text-nowrap" translate="no">${code}</code>`
 }
 
-// Custom link renderer, to update bootstrap docs version in href
+// Custom link renderer, to update Bootstrap docs version in href
 // Only applies to markdown links (not explicit `<a href="..">...</a>` tags
 renderer.link = (href, title, text) => {
   let target = ''
@@ -92,7 +117,7 @@ renderer.heading = function(text, level, raw, slugger) {
   return `<h${level} ${attrs}>${getTextMarkup(text + anchor)}</h${level}>\n`
 }
 
-// Convert lead-in blockquote paragraphs to true bootstrap docs leads
+// Convert lead-in blockquote paragraphs to true Bootstrap docs leads
 renderer.blockquote = function(text) {
   return text.replace('<p>', '<p class="bd-lead">')
 }
@@ -107,6 +132,8 @@ renderer.table = function() {
   return `<div class="table-responsive-sm">${table}</div>`
 }
 
+// --- Main export ---
+
 module.exports = {
   srcDir: __dirname,
 

docs/plugins/play.js

@@ -5,10 +5,10 @@ import hljs from '../utils/hljs'
 
 // --- Constants ---
 
-const NAME_REGEX = /<!-- (.*)\.vue -->/
-const NAME_DEFINITION_REGEX = /<!-- .*\.vue -->/
-const TEMPLATE_REGEX = /<template>([\s\S]*)<\/template>/
-const SCRIPT_REGEX = /<script>([\s\S]*)<\/script>/
+const RX_NAME = /<!-- (.*)\.vue -->/
+const RX_NAME_DEFINITION = /<!-- .*\.vue -->/
+const RX_TEMPLATE = /<template>([\s\S]*)<\/template>/
+const RX_SCRIPT = /<script>([\s\S]*)<\/script>/
 
 const CLASS_NAMES = {
   editable: 'editable',
@@ -25,8 +25,8 @@ const match = (regex, text) => (regex.exec(text) || [])[1]
 const removeNode = node => node && node.parentNode && node.parentNode.removeChild(node)
 
 const parseVueTemplate = text => {
-  let template = match(TEMPLATE_REGEX, text)
-  const script = match(SCRIPT_REGEX, text)
+  let template = match(RX_TEMPLATE, text)
+  const script = match(RX_SCRIPT, text)
   const options = {}
 
   // It is plain code
@@ -58,15 +58,16 @@ const createVM = (name, node, vnode) => {
 
     const { template, options } = vt
 
-    // Create a placeholder after node
+    // Create a placeholder after node container
+    const container = node.parentNode
     const holder = document.createElement('div')
-    node.parentNode.insertBefore(holder, node)
+    container.parentNode.insertBefore(holder, container)
 
     // Create VM
     return new Vue({
       ...options,
       el: holder,
-      template: `<div class="bd-example vue-example vue-example-${name} notranslate" translate="no">${template}</div>`,
+      template: `<div class="bd-example vue-example vue-example-${name}" translate="no">${template}</div>`,
       router: vnode.context.$router
     })
   } catch (e) {
@@ -96,20 +97,20 @@ const processExamples = (el, binding, vnode) => {
   }
 
   // Get all code-snippets
-  const pres = [...el.querySelectorAll('pre.hljs')]
+  const pres = [...el.querySelectorAll('.bd-code pre')]
 
   // Iterate over them and parse
   pres.forEach(pre => {
     // Store example name globally
-    const name = match(NAME_REGEX, pre.textContent)
+    const name = match(RX_NAME, pre.textContent)
 
     // Exit early when no name is given
     if (!name) {
       return
     }
 
     // Remove name definition
-    const text = pre.textContent.replace(NAME_DEFINITION_REGEX, '').trim()
+    const text = pre.textContent.replace(RX_NAME_DEFINITION, '').trim()
     pre.textContent = text
 
     // Highlight again

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

@@ -1,4 +1,4 @@
-// Adds control sizing to bootstrap custom checkbox/switch inputs
+// Adds control sizing to Bootstrap custom checkbox/switch inputs
 
 .custom-checkbox.b-custom-control-lg,
 .input-group-lg .custom-checkbox {

src/components/form-input/README.md

@@ -582,7 +582,7 @@ these methods and properties. Support will vary based on input type.
 
 ## Using HTML5 `<input>` as an alternative
 
-If you just need a simple input with basic bootstrap styling, you can simply use the following:
+If you just need a simple input with basic Bootstrap styling, you can simply use the following:
 
 ```html
 <template>

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

@@ -1,4 +1,4 @@
-// Adds control sizing to bootstrap custom radio inputs
+// Adds control sizing to Bootstrap custom radio inputs
 
 .custom-radio.b-custom-control-lg,
 .input-group-lg .custom-radio {

src/components/table/README.md

@@ -1567,7 +1567,7 @@ will be using other means to convey that a row is selected (such as a scoped fie
 example).
 
 The `selected-variant` can be any of the
-[standard (or custom) bootstrap base color variants](/docs/reference/color-variants), or the special
+[standard (or custom) Bootstrap base color variants](/docs/reference/color-variants), or the special
 [table `active` variant](/docs/reference/color-variants#table-variants) (the default) which takes
 precedence over any specific row or cell variants.
 

src/icons/README.md

@@ -192,7 +192,7 @@ unless you are using the `IconsPlugin` or `BootstrapVueIcons` plugin.
 ## Variants
 
 By default, icons inherit the current text color of their parent element. All icon components
-provide a `variant` prop to apply one of the bootstrap contextual text variant colors:
+provide a `variant` prop to apply one of the Bootstrap contextual text variant colors:
 
 ```html
 <template>