docs: Use Markdown

Markdown produces nicer output where supported, so use that instead
of plain ASCII formatting.

7 files changed, 97 insertions, 99 deletions

diff --git a/HACKING b/HACKING.md
index 575be5b7a..8c064999a 100644
--- a/HACKING
+++ b/HACKING.md
@@ -1,19 +1,16 @@
-Coding guide
-============
+# Coding guide
 
 Our goal is to have all JavaScript code in GNOME follow a consistent style. In
 a dynamic language like JavaScript, it is essential to be rigorous about style
 (and unit tests), or you rapidly end up with a spaghetti-code mess.
 
-A quick note
-------------
+## A quick note
 
 Life isn't fun if you can't break the rules. If a rule seems unnecessarily
 restrictive while you're coding, ignore it, and let the patch reviewer decide
 what to do.
 
-Indentation and whitespace
---------------------------
+## Indentation and whitespace
 
 Use four-space indents. Braces are on the same line as their associated
 statements.  You should only omit braces if *both* sides of the statement are
@@ -22,7 +19,7 @@ on one line.
 * One space after the `function` keyword.  No space between the function name
 * in a declaration or a call.  One space before the parens in the `if`
 * statements, or `while`, or `for` loops.
-
+```javascript
     function foo(a, b) {
         let bar;
 
@@ -39,22 +36,20 @@ on one line.
             print(20);
         }
     }
+```
 
-Semicolons
-----------
+## Semicolons
 
 JavaScript allows omitting semicolons at the end of lines, but don't. Always
 end statements with a semicolon.
 
-js2-mode
---------
+## js2-mode
 
 If using Emacs, do not use js2-mode. It is outdated and hasn't worked for a
 while. emacs now has a built-in JavaScript mode, js-mode, based on
 espresso-mode. It is the de facto emacs mode for JavaScript.
 
-File naming and creation
-------------------------
+## File naming and creation
 
 For JavaScript files, use lowerCamelCase-style names, with a `.js` extension.
 
@@ -67,14 +62,13 @@ library name followed by a dash, e.g. `shell-app-system.c`. Create a
 `-private.h` header when you want to share code internally in the
 library. These headers are not installed, distributed or introspected.
 
-Imports
--------
+## Imports
 
 Use UpperCamelCase when importing modules to distinguish them from ordinary
 variables, e.g.
-
+```javascript
     const GLib = imports.gi.GLib;
-
+```
 Imports should be categorized into one of two places. The top-most import block
 should contain only "environment imports". These are either modules from
 gobject-introspection or modules added by gjs itself.
@@ -85,7 +79,7 @@ e.g. `imports.ui.popupMenu`.
 
 Each import block should be sorted alphabetically. Don't import modules you
 don't use.
-
+```javascript
     const GLib = imports.gi.GLib;
     const Gio = imports.gi.Gio;
     const Lang = imports.lang;
@@ -95,23 +89,22 @@ don't use.
     const Params = imports.misc.params;
     const Tweener = imports.ui.tweener;
     const Util = imports.misc.util;
-
+```
 The alphabetical ordering should be done independently of the location of the
 location. Never reference `imports` in actual code.
 
-Constants
----------
+## Constants
 
 We use CONSTANTS_CASE to define constants. All constants should be directly
 under the imports:
-
+```javascript
     const MY_DBUS_INTERFACE = 'org.my.Interface';
+```
 
-Variable declaration
---------------------
+## Variable declaration
 
 Always use either `const` or `let` when defining a variable.
-
+```javascript
     // Iterating over an array
     for (let i = 0; i < arr.length; ++i) {
         let item = arr[i];
@@ -121,17 +114,17 @@ Always use either `const` or `let` when defining a variable.
     for (let prop in someobj) {
         ...
     }
+```
 
 If you use "var" then the variable is added to function scope, not block scope.
 See [What's new in JavaScript 1.7](https://developer.mozilla.org/en/JavaScript/New_in_JavaScript/1.7#Block_scope_with_let_%28Merge_into_let_Statement%29)
 
-Classes
--------
+## Classes
 
 There are many approaches to classes in JavaScript. We use our own class framework
 (sigh), which is built in gjs. The advantage is that it supports inheriting from
 GObjects, although this feature isn't used very often in the Shell itself.
-
+```javascript
     var IconLabelMenuItem = new Lang.Class({
         Name: 'IconLabelMenuItem',
         Extends: PopupMenu.PopupMenuBaseItem,
@@ -146,6 +139,7 @@ GObjects, although this feature isn't used very often in the Shell itself.
             log("menu opened!");
         }
     });
+```
 
 * 'Name' is required. 'Extends' is optional. If you leave it out, you will
   automatically inherit from Object.
@@ -162,13 +156,12 @@ GObjects, although this feature isn't used very often in the Shell itself.
   still a giant function call, even though it may resemble a more
   conventional syntax.
 
-GObject Introspection
----------------------
+## GObject Introspection
 
 GObject Introspection is a powerful feature that allows us to have native
 bindings for almost any library built around GObject. If a library requires
 you to inherit from a type to use it, you can do so:
-
+```javascript
     var MyClutterActor = new Lang.Class({
         Name: 'MyClutterActor',
         Extends: Clutter.Actor,
@@ -188,9 +181,9 @@ you to inherit from a type to use it, you can do so:
                             alloc.x2, alloc.y2);
         }
     });
+```
 
-Translatable strings, `environment.js`
---------------------------------------
+## Translatable strings, `environment.js`
 
 We use gettext to translate the GNOME Shell into all the languages that GNOME
 supports. The `gettext` function is aliased globally as `_`, you do not need to
@@ -204,8 +197,7 @@ and "double quotes" for strings that the user may see. This allows us to
 quickly find untranslated or mistranslated strings by grepping through the
 sources for double quotes without a gettext call around them.
 
-`actor` and `_delegate`
------------------------
+## `actor` and `_delegate`
 
 gjs allows us to set so-called "expando properties" on introspected objects,
 allowing us to treat them like any other. Because the Shell was built before
@@ -214,7 +206,7 @@ that has a property called `actor`. We call this wrapper class the "delegate".
 
 We sometimes use expando properties to set a property called `_delegate` on
 the actor itself:
-
+```javascript
     var MyClass = new Lang.Class({
         Name: 'MyClass',
 
@@ -229,6 +221,7 @@ the actor itself:
             actor.set_label("You clicked the button!");
         }
     });
+```
 
 The 'delegate' property is important for anything which trying to get the
 delegate object from an associated actor. For instance, the drag and drop
@@ -236,16 +229,14 @@ system calls the `handleDragOver` function on the delegate of a "drop target"
 when the user drags an item over it. If you do not set the `_delegate`
 property, your actor will not be able to be dropped onto.
 
-Functional style
-----------------
+## Functional style
 
 JavaScript Array objects offer a lot of common functional programming
 capabilities such as forEach, map, filter and so on. You can use these when
 they make sense, but please don't have a spaghetti mess of function programming
 messed in a procedural style. Use your best judgment.
 
-Closures
---------
+## Closures
 
 `this` will not be captured in a closure, it is relative to how the closure is
 invoked, not to the value of this where the closure is created, because "this"
@@ -254,15 +245,16 @@ variable that can be captured in closures.
 
 All closures should be wrapped with Function.prototype.bind or use arrow
 notation.
-
+```javascript
     const Lang = imports.lang;
 
     let closure1 = () => { this._fnorbate(); };
     let closure2 = this._fnorbate.bind(this);
+```
 
 A more realistic example would be connecting to a signal on a method of a
 prototype:
-
+```javascript
     const Lang = imports.lang;
     const FnorbLib = imports.fborbLib;
 
@@ -276,19 +268,21 @@ prototype:
             this._updateFnorb();
         }
     });
+```
 
-Object literal syntax
----------------------
+## Object literal syntax
 
 In JavaScript, these are equivalent:
-
+```javascript
     foo = { 'bar': 42 };
     foo = { bar: 42 };
+```
 
 and so are these:
-
+```javascript
     var b = foo['bar'];
     var b = foo.bar;
+```
 
 If your usage of an object is like an object, then you're defining "member
 variables." For member variables, use the no-quotes no-brackets syntax: `{ bar:
@@ -298,14 +292,13 @@ If your usage of an object is like a hash table (and thus conceptually the keys
 can have special chars in them), don't use quotes, but use brackets: `{ bar: 42
 }`, `foo['bar']`.
 
-Getters, setters, and Tweener
------------------------------
+## Getters, setters, and Tweener
 
 Getters and setters should be used when you are dealing with an API that is
 designed around setting properties, like Tweener. If you want to animate an
 arbitrary property, create a getter and setter, and use Tweener to animate the
 property.
-
+```javascript
     var ANIMATION_TIME = 2000;
 
     var MyClass = new Lang.Class({
@@ -331,3 +324,4 @@ property.
                      { position: 100,
                        time: ANIMATION_TIME,
                        transition: 'easeOutQuad' });
+```
diff --git a/README b/README.md
index 0bfcf5c09..6bec164c4 100644
--- a/README
+++ b/README.md
@@ -1,3 +1,4 @@
+# GNOME Shell
 GNOME Shell provides core user interface functions for the GNOME 3 desktop,
 like switching to windows and launching applications. GNOME Shell takes
 advantage of the capabilities of modern graphics hardware and introduces
@@ -6,15 +7,14 @@ easy to use experience.
 
 For more information about GNOME Shell, including instructions on how
 to build GNOME Shell from source and how to get involved with the project,
-see:
+see the [project wiki][wiki]
 
- https://wiki.gnome.org/Projects/GnomeShell
+Bugs should be reported to the GNOME [bug tracking system][bug-tracker].
 
-Bugs should be reported at http://bugzilla.gnome.org against the 'gnome-shell'
-product.
-
-License
-=======
+## License
 GNOME Shell is distributed under the terms of the GNU General Public License,
-version 2 or later. See the COPYING file for details.
+version 2 or later. See the [COPYING][license] file for details.
 
+[project-wiki]: https://wiki.gnome.org/Projects/GnomeShell
+[bug-tracker]: https://gitlab.gnome.org/GNOME/gnome-shell/issues
+[license]: COPYING
diff --git a/browser-plugin/README b/browser-plugin/README.md
index 9eccb7ca3..8952e2bf3 100644
--- a/browser-plugin/README
+++ b/browser-plugin/README.md
@@ -4,14 +4,14 @@ the extensions repository to provide good integration, letting the website
 know which extensions are enabled and disabled, and allowing the website to
 enable, disable and install them.
 
-Bugs should be reported at http://bugzilla.gnome.org against the 'gnome-shell'
-product.
+Bugs should be reported to the GNOME [bug tracking system][bug-tracker].
 
-License
-=======
+## License
 The GNOME Shell Browser Plugin, like GNOME Shell itself is distributed under
 the GNU General Public License, version 2 or later. The plugin also contains
 header files from the "NPAPI SDK" project, tri-licensed under MPL 1.1, GPL 2.0
 and LGPL 2.1. These headers are third-party sources and can be retrieved from:
 
   http://code.google.com/p/npapi-sdk/
+
+[bug-tracker]: https://gitlab.gnome.org/GNOME/gnome-shell/issues
diff --git a/data/theme/README b/data/theme/README
deleted file mode 100644
index 688892dba..000000000
--- a/data/theme/README
+++ /dev/null
@@ -1,31 +0,0 @@
-Summary
--------
-
-* Do not edit the CSS directly, edit the source SCSS files and the CSS files will be generated
-  automatically when building with meson + ninja and left inside the build directory to be
-  incorporated into the gresource XML (you'll need to have sassc installed).
-
-How to tweak the theme
-----------------------
-
-Adwaita is a complex theme, so to keep it maintainable it's written and processed in SASS, the
-generated CSS is then transformed into a gresource file during gtk build and used at runtime in a 
-non-legible or editable form.
-
-It is very likely your change will happen in the _common.scss file. That's where all the widget 
-selectors are defined. Here's a rundown of the "supporting" stylesheets, that are unlikely to be the 
-right place for a drive by stylesheet fix:
-
-_colors.scss        - global color definitions. We keep the number of defined colors to a necessary minimum, 
-                      most colors are derived from a handful of basics. It is an exact copy of the gtk+ 
-                      counterpart. Light theme is used for the classic theme and dark is for GNOME3 shell 
-                      default.
-
-_drawing.scss       - drawing helper mixings/functions to allow easier definition of widget drawing under
-                      specific context. This is why Adwaita isn't 15000 LOC.
-
-_common.scss        - actual definitions of style for each widget. This is where you are likely to add/remove
-                      your changes.
-                      
-You can read about SASS at http://sass-lang.com/documentation/. Once you make your changes to the
-_common.scss file, you can run ninja to generate the final CSS files.
diff --git a/data/theme/README.md b/data/theme/README.md
new file mode 100644
index 000000000..192dc65e4
--- /dev/null
+++ b/data/theme/README.md
@@ -0,0 +1,32 @@
+## Summary
+
+Do not edit the CSS directly, edit the source SCSS files and the CSS files
+will be generated automatically when building with meson + ninja and left
+inside the build directory to be incorporated into the gresource XML (you'll
+need to have sassc installed).
+
+## How to tweak the theme
+
+Adwaita is a complex theme, so to keep it maintainable it's written and
+processed in SASS, the generated CSS is then transformed into a gresource
+file during gtk build and used at runtime in a non-legible or editable form.
+
+It is very likely your change will happen in the [_common.scss][common] file.
+That's where all the widget selectors are defined. Here's a rundown of
+the "supporting" stylesheets, that are unlikely to be the right place
+for a drive by stylesheet fix:
+
+| File                     | Description       |
+| ------------------------ | ----------------- |
+| [_colors.scss][colors]   | global color definitions. We keep the number of defined colors to a necessary minimum,  most colors are derived from a handful of basics. It is an exact copy of the gtk+ counterpart. Light theme is used for the classic theme and dark is for GNOME3 shell default. |
+| [_drawing.scss][drawing] | drawing helper mixings/functions to allow easier definition of widget drawing under specific context. This is why Adwaita isn't 15000 LOC. |
+| [_common.scss][common]   | actual definitions of style for each widget. This is where you are likely to add/remove your changes. |
+
+You can read about SASS on its [web page][sass-web]. Once you make your
+changes to the [_common.scss][common] file, you can run ninja to generate the
+final CSS files.
+
+[common]: data/theme/gnome-shell-sass/_common.scss
+[colors]: data/theme/gnome-shell-sass/_colors.scss
+[drawing]: data/theme/gnome-shell-sass/_drawing.scss
+[sass-web]: http://sass-lang.com/documentation/
diff --git a/data/theme/gnome-shell-sass/README b/data/theme/gnome-shell-sass/README
deleted file mode 100644
index 7f2a257e8..000000000
--- a/data/theme/gnome-shell-sass/README
+++ /dev/null
@@ -1,7 +0,0 @@
-GNOME Shell Sass is a project intended to allow the sharing of the theme sources in sass between gnome-shell and other projects like gnome-shell-extensions.
-
-License
-=======
-GNOME Shell Sass is distributed under the terms of the GNU General Public License,
-version 2 or later. See the COPYING file for details.
-
diff --git a/data/theme/gnome-shell-sass/README.md b/data/theme/gnome-shell-sass/README.md
new file mode 100644
index 000000000..7d6090ffe
--- /dev/null
+++ b/data/theme/gnome-shell-sass/README.md
@@ -0,0 +1,10 @@
+# GNOME Shell Sass
+GNOME Shell Sass is a project intended to allow the sharing of the
+theme sources in sass between gnome-shell and other projects like
+gnome-shell-extensions.
+
+## License
+GNOME Shell Sass is distributed under the terms of the GNU General Public
+License, version 2 or later. See the [COPYING][license] file for details.
+
+[license]: COPYING