NEW Add anchor links to headings (#219)

* DOC Update and restructure README for clarity and accuracy

* NEW Add anchor links to headings

README.md

@@ -11,17 +11,15 @@ site generator based on [React](https://reactjs.org). It sources content
 from the [framework](https://github.com/silverstripe/silverstripe-framework)
 repository for each major release.
 
-**This repository does NOT contain the most current documentation.**
+**This repository does NOT contain any documentation.**
 
-The documentation files are written in the
+The developer documentation is stored in the framework module
-[markdown](https://docs.silverstripe.org/en/2.4/misc/ss-markdown/)
+repository, in the `docs` folder. For example, the documentation for the
-format and the most current versions of these files and are not stored
+master branch of Silverstripe CMS is stored in
-here. Instead, they are stored in a `docs` folder alongside the
-framework source code in each framework repository. For example, the
-documentation markdown files for the master branch of the SilverStripe framework are
-stored in
 [https://github.com/silverstripe/silverstripe-framework/tree/master/docs](https://github.com/silverstripe/silverstripe-framework/tree/master/docs).
 
+The userhelp documentation is stored in the [userhelp-content repo](https://github.com/silverstripe/silverstripe-userhelp-content/).
+
 ## Installation
 
 To set up a local instance of [doc.silverstripe.org](https://github.com/silverstripe/doc.silverstripe.org):
@@ -44,6 +42,13 @@ No local NodeJS nor gatsby-cli is required for this option.
 
 * Install [Gatsby CLI](https://gatsbyjs.com)
 
+## Developing
+
+Once cloned, from the root of the repository, run the command `yarn dev-docs`
+to instantiate a development server. This will consume all of the markdown files in both major release
+branches and allow you to browse the developer documentation site on `http://localhost:8000` by default
+(see the [Gatsby docs](https://www.gatsbyjs.org/docs/) for instructions on customising the port).
+
 ## Building
 
 To test a static build of the site, first create a production environment file.
@@ -55,8 +60,8 @@ cp .env.development .env.production
 Then, run the build.
 
 ```
-gatsby build
+yarn build-docs
-gatsby serve
+yarn serve
 ```
 
 These commands will give you an exact representation of how the site will run on a production server, with
@@ -75,18 +80,6 @@ yarn build-docs
 yarn build-user
 ```
 
-
-## Developing
-
-From within `path/to/ssdocs`, run the command
-
-```
-gatsby develop
-```
-to instantiate a development server. This will consume all of the markdown files in both major release
-branches and allow you to browse the documentation site on `http://localhost:8000` by default
-(see the [Gatsby docs](https://www.gatsbyjs.org/docs/) for instructions on customising the port).
-
 ## Authoring
 
 You can make changes directly to the source markdown files and get live updates in the development

src/theme/assets/scss/theme/_docs.scss

@@ -270,6 +270,28 @@
 		
 	}
 
+	.anchor {
+		color: $theme-text-color-light;
+		margin-left: 1rem;
+		opacity: 0;
+		transition: opacity .2s;
+
+		/* Force anchor link to offset header */
+		margin-top: -90px;
+		padding-top: 90px;
+
+		&:focus {
+			opacity: 1;
+
+			/* Outline behaves incorrectly due to offset, use underline instead */
+			outline: none;
+			text-decoration: underline;
+		}
+	}
+	:hover > .anchor {
+		opacity: 1;
+	}
+	
 	.section-heading {
 		font-size: 1.875rem;
 		margin-bottom: 1rem;

src/utils/rewriteHeader.ts

@@ -33,10 +33,22 @@ const rewriteHeaders = (domNode: DomElement): ReactElement | false => {
             id = generateID(data);
         }
 
+        const anchor = createElement(
+          'a',
+          {
+              "aria-hidden": true,
+              className: 'anchor',
+              href: `#${id}`,
+              id,
+              key: id,
+          },
+          '#'
+        );
+
         return createElement(
             domNode.name,
-            { id },
+            {},
-            header
+            [ header, anchor ]
         );
 
     }