1 files changed, 34 insertions, 0 deletions
diff --git a/devtools/docs/user/debugger/how_to/use_a_source_map/index.rst b/devtools/docs/user/debugger/how_to/use_a_source_map/index.rst
new file mode 100644
index 0000000000..e78bdc905b
--- /dev/null
+++ b/devtools/docs/user/debugger/how_to/use_a_source_map/index.rst
@@ -0,0 +1,34 @@
+================
+Use a source map
+================
+
+The JavaScript sources executed by the browser are often transformed in some way from the original sources created by a developer. For example:
+
+- sources are often combined and `minified <https://en.wikipedia.org/wiki/Minification_(programming)>`_ to make delivering them from the server more efficient.
+
+- JavaScript running in a page is often machine-generated, as when compiled from a language like `CoffeeScript <https://coffeescript.org/>`_ or `TypeScript <https://www.typescriptlang.org/>`_
+
+In these situations, it's much easier to debug the original source, rather than the source in the transformed state that the browser has downloaded. A `source map <https://www.html5rocks.com/en/tutorials/developertools/sourcemaps/>`_ is a file that maps from the transformed source to the original source, enabling the browser to reconstruct the original source and present the reconstructed original in the debugger.
+
+To enable the debugger to work with a source map, you must:
+
+- generate the source map
+- include a comment in the transformed file, that points to the source map. The comment's syntax is like this:
+
+.. code-block:: JavaScript
+
+  //# sourceMappingURL=http://example.com/path/to/your/sourcemap.map
+
+.. raw:: html
+
+  <iframe width="560" height="315" src="https://www.youtube.com/embed/Fqd15gHC4Pg" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+  <br/>
+  <br/>
+
+In the video above we load https://firefox-devtools.github.io/devtools-examples/sourcemaps-in-console/index.html. This page loads a source called "main.js" that was originally written in CoffeeScript and compiled to JavaScript. The compiled source contains a comment like this, that points to a source map:
+
+.. code-block:: JavaScript
+
+  //# sourceMappingURL=main.js.map
+
+In the Debugger's :ref:`source list pane <debugger-ui-tour-source-list-pane>`, the original CoffeeScript source now appears as "main.coffee", and we can debug it just like any other source.