Docs improvements: Build-time Syntax highlighting, scroll perf improv…

…ements, docs dev/deployment fixes (#38)

package.json

@@ -63,6 +63,7 @@
  "postcss-nested": "^3.0.0",
  "postcss-remtopx": "^1.0.0",
  "postcss-svg": "^2.1.0",
+ "prismjs": "^1.15.0",
  "readable-stream": "^2.3.5",
  "run-sequence": "^1.2.2",
  "svgmin": "^0.1.0",

tasks/build-docs.js

@@ -42,6 +42,14 @@ gulp.task('build-docs:copy-site-resources', function() {
  .pipe(gulp.dest('dist/docs'));
 });
 
+gulp.task('build-docs:copy-prism-resources', function() {
+ return gulp.src([
+ 'node_modules/prismjs/themes/prism.css',
+ 'node_modules/prismjs/themes/prism-tomorrow.css'
+ ])
+ .pipe(gulp.dest('dist/docs/css/vendor/'));
+});
+
 
 gulp.task('build-docs:copy-polyfill', function() {
  return gulp.src([
@@ -76,6 +84,7 @@ gulp.task('build-docs',
  'build-docs:topdoc',
  gulp.parallel(
  'build-docs:copy-site-resources',
+ 'build-docs:copy-prism-resources',
  'build-docs:copy-polyfill',
  'build-docs:copy-spectrum-icons'
  ),

tasks/dev.js

@@ -45,11 +45,11 @@ function watch() {
  'docs/**/*.yml',
  'topdoc/lib/template.pug',
  'topdoc/lib/index.js',
- '../topdoc/resources/js/*.js'
+ 'topdoc/resources/js/*.js'
  ], gulp.series('reload-docs'));
 
  gulp.watch([
- '../topdoc/resources/css/*.css'
+ 'topdoc/resources/css/*.css'
  ], gulp.series('reload-docs-css'));
 
  gulp.watch('icons/*.svg', gulp.series('reload-icons'));

tasks/gh-pages.js

@@ -9,14 +9,14 @@ var package = JSON.parse(fs.readFileSync('./package.json'));
  * Replace the redirect path to latest version
  */
 gulp.task('gh-pages:prepare-docs', function () {
- return gulp.src('../topdoc/resources/gh-pages.html')
+ return gulp.src('topdoc/resources/gh-pages.html')
  .pipe(template({ version: package.version }))
  .pipe(rename('index.html'))
  .pipe(gulp.dest('./temp'));
 });
 
 gulp.task('gh-pages:prepare-icons', function () {
- return gulp.src('../topdoc/resources/gh-pages-icons.html')
+ return gulp.src('topdoc/resources/gh-pages-icons.html')
  .pipe(template({ version: package.version }))
  .pipe(rename('index.html'))
  .pipe(gulp.dest('./temp/icons/'));

topdoc/lib/index.js

@@ -4,6 +4,7 @@ var pug = require('pug');
 var path = require('path');
 var markdown = require('markdown').markdown;
 var fsExtra = require('fs-extra');
+var Prism = require('prismjs');
 
 const labelColors = {
  'Deprecated': 'red',
@@ -46,6 +47,13 @@ function replaceExt(npath, ext) {
  return path.join(path.dirname(npath), nFileName);
 }
 
+function processMarkup(markup) {
+ if (markup) {
+ return Prism.highlight(markup, Prism.languages.markup, 'markup');
+ }
+ return '';
+}
+
 /**
  * Public: creates docs using topDocument data with a pug template.
  *
@@ -120,6 +128,7 @@ function template(topDocument) {
  // Add other data
  component.id = dnaComponentId;
  component.description = component.description || '';
+ component.highlightedMarkup = processMarkup(component.markup);
 
  if (component.components) {
  var extraComponentDescriptions = '';
@@ -128,6 +137,7 @@ function template(topDocument) {
  if (typeof component.components[subComponentId] === 'string') {
  // Shorthand
  subComponent.markup = component.components[subComponentId];
+ subComponent.highlightedMarkup = processMarkup(subComponent.markup);
  subComponent.id = subComponentId;
  }
  else {

topdoc/lib/template.pug

@@ -6,7 +6,7 @@ html.spectrum--medium
  title Spectrum CSS Documentation
  meta(name="viewport", content="user-scalable=no,initial-scale = 1.0,maximum-scale = 1.0")
 
- link(rel='stylesheet', type='text/css', href='css/vendor/github.css', data-rainbow)
+ link(rel='stylesheet', type='text/css', href='css/vendor/prism.css', data-prism)
  link(rel='stylesheet', type='text/css', href='../spectrum-core.css', data-spectrum-core)
  link(rel='stylesheet', type='text/css', href='', data-spectrum-core-diff)
  link(rel='stylesheet', type='text/css', href='../spectrum-lightest.css')
@@ -121,7 +121,7 @@ html.spectrum--medium
  if subComponent.markup.split('\n').length > 2
  a.js-markup-toggle.cssdocs-example-markupToggle.spectrum-Link(href="#") Show Markup
  pre
- code(data-language="html")=subComponent.markup
+ code.language-markup!=subComponent.highlightedMarkup
 
 
  else if component.markup
@@ -131,9 +131,8 @@ html.spectrum--medium
  if component.markup.split('\n').length > 2
  a.js-markup-toggle.cssdocs-example-markupToggle.spectrum-Link(href="#") Show Markup
  pre
- code(data-language="html")=component.markup
+ code.language-markup!=component.highlightedMarkup
 
  div.spectrum-Underlay#spectrum-underlay
 
- script(type="text/javascript", src='js/vendor/rainbow-custom.min.js')
  script(type="text/javascript", src='js/vendor/typekit.js')

topdoc/resources/css/docs.css

@@ -139,6 +139,11 @@ pre code {
  white-space: pre-wrap;
 }
 
+code[class*="language-"], pre[class*="language-"] {
+ text-shadow: none;
+ font-size: 12px;
+}
+
 .cssdocs-example-markupToggle {
  position: absolute;
  z-index: 1;
@@ -194,6 +199,7 @@ pre code {
  overflow-x: hidden;
 
  -webkit-overflow-scrolling: touch;
+ will-change: transform;
 }
 
 .sdldocs-splitview {