From 03d89d1eb73f2c85caac7868a2805fa885247166 Mon Sep 17 00:00:00 2001 From: Dan Allen Date: Fri, 27 Mar 2020 12:20:41 -0600 Subject: [PATCH] rework description of source maps and move to section about bundle --- README.adoc | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/README.adoc b/README.adoc index 3d5c39e..ec64d04 100644 --- a/README.adoc +++ b/README.adoc @@ -17,7 +17,7 @@ :url-nodejs: https://nodejs.org :url-nvm: https://github.com/creationix/nvm :url-nvm-install: {url-nvm}#installation -:url-sourcemap-information: https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Use_a_source_map +:url-source-maps: https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Use_a_source_map image:{img-ci-status}[CI Status (GitLab CI), link={url-ci-pipelines}] @@ -167,17 +167,6 @@ This works by monitoring the project for changes, running the `preview:build` ta Press kbd:[Ctrl+C] to stop the preview server and end the continuous build. -==== Source Maps - -In preview mode, {url-sourcemap-information}[source maps] are enabled. -This means that although Javascript and CSS files are combined into a single file (`site.js` or `site.css`) an additional `map` file is provided to allow a reference to the source. -This is especially useful for debugging. - -This is mainly intended for preview and debugging not for production. -If you need this capability in production it can be achieved through an environment variable when bundling the UI: - - $ SOURCEMAPS=true gulp build - === Package for Use with Antora If you need to package the UI so you can use it to generate the documentation site locally, run the following command: @@ -195,6 +184,22 @@ If you have the preview running, and you want to bundle without causing the prev The UI bundle will again be available at [.path]_build/ui-bundle.zip_. +==== Source Maps + +The build consolidates all the CSS and client-side JavaScript into combined files, [.path]_site.css_ and [.path]_site.js_, respectively, in order to reduce the size of the bundle. +{url-source-maps}[Source maps] correlate these combined files with their original sources. + +This "`source mapping`" is accomplished by generating additional map files that make this association. +These map files sit adjacent to the combined files in the build folder. +The mapping they provide allows the debugger to present the original source rather than the obfuscated file, an essential tool for debugging. + +In preview mode, source maps are enabled automatically, so there's nothing you have to do to make use of them. +If you need to include source maps in the bundle, you can do so by setting the `SOURCEMAPS` environment varible to `true` when you run the bundle command: + + $ SOURCEMAPS=true gulp bundle + +In this case, the bundle will include the source maps, which can be used for debuggging your production site. + == Copyright and License Copyright (C) 2017-2019 OpenDevise Inc. and the Antora Project. -- 2.11.0