Mkdocs

INSTALL.md

@@ -1,12 +1,5 @@
 # BLT installation and updates
 
-* System requirements
-* [Creating a new project with BLT](#creating-new)
-* [Adding BLT to an existing project](#existing-project)
-* [Updating to the latest version of BLT](#updating)
-  * [Updating from a non-composer-managed version](#update-non-composered)
-  * [Updating a composer-managed version](#update-composered)
-
 ## System Requirements
 
 You should be able to use the following tools on the command line of your native operating system:
@@ -23,99 +16,90 @@ You should be able to use the following tools on the command line of your native
 
 * Globally install pretissimo for parallelized composer downloads:
 
-  ```
-  composer global require "hirak/prestissimo:^0.3"
-  ```
+        composer global require "hirak/prestissimo:^0.3"
+
 * If you have xDebug enabled for your PHP CLI binary, it is highly recommended that you disable it to dramatically improve performance.
 
-## <a name="creating-new"></a>Creating a new project with BLT
+## Creating a new project with BLT
 
 1. Create a new project using the [blt-project](https://github.com/acquia/blt-project) template:
 
-  ```
-  composer create-project acquia/blt-project:8.x-dev MY_PROJECT --no-interaction
-  cd MY_PROJECT
-  ```
+        composer create-project acquia/blt-project:8.x-dev MY_PROJECT --no-interaction
+        cd MY_PROJECT
+
 1. Install the `blt` alias and follow on-screen instructions:
 
-  ```
-  ./vendor/bin/blt install-alias
-  ```
+        ./vendor/bin/blt install-alias
+
 1. Customize BLT configuration files:
-  * `project.yml`
-  * `docroot/sites/default/settings/local.settings.php`
-    * Add your local DB credentials to `$databases`
+    * `project.yml`
+    * `docroot/sites/default/settings/local.settings.php`
+        * Add your local DB credentials to `$databases`
 1. Replace tokens in new BLT-generated files with your custom values in project.yml:
 
-  ```
-  blt configure
-  ```
+
+        blt configure
+
 1. (optional) Modify project files. Important files that you may want to modify include:
-  * composer.json. Note that Drupal core, contrib, and third party dependencies are all managed here.
-  * Project’s root README.md.
-  * Other project documentation in the readme directory.
+    * composer.json. Note that Drupal core, contrib, and third party dependencies are all managed here.
+    * Project’s root README.md.
+    * Other project documentation in the readme directory.
 1. (optional) Follow instructions for <a href="#install">installing Drupal locally</a>.
 
-## <a name="existing-project"></a>Adding BLT to an existing project
+## Adding BLT to an existing project
 
 To add BLT to a pre-existing Drupal project, do the following:
 
 1. Ensure that your project directory structure is Acquia-cloud compatible by asserting that the Drupal root is in a top-level folder called `docroot`.
 1. If you currently manage your dependencies via Composer, ensure that they are all up to date via `composer update`. Assert that these updates do not break your project.
 1. `cd` into your existing project directory.
 1. Add BLT via composer and initialize it:
-  ```
-  composer require acquia/blt:~8
-  ./vendor/acquia/blt/blt.sh init
-  ```
+
+        composer require acquia/blt:~8
+        ./vendor/acquia/blt/blt.sh init
+
 1. (optional) Modify project files. Important files that you may want to modify include:
-  * composer.json. Note that Drupal core, contrib, and third party dependencies are all managed here.
-  * Project’s root README.md.
-  * Other project documentation in the readme directory.
+    * composer.json. Note that Drupal core, contrib, and third party dependencies are all managed here.
+    * Project’s root README.md.
+    * Other project documentation in the readme directory.
 1. (optional) Follow instructions for <a href="#install">installing Drupal locally</a>.
 
-## <a name="updating"></a>Updating BLT
+## Updating BLT
 
-### <a name="update-composered"></a>Updating a composer-managed version
+### Updating a composer-managed version
 
 If you are already using BLT via Composer, you can update to the latest version of BLT by running the following commands from your project's root directory:
 
-```
-composer update acquia/blt
-blt update
-```
+      composer update acquia/blt
+      blt update
+
 
-### <a name="update-non-composered"></a>Updating from a non-Composer-managed version
+### Updating from a non-Composer-managed version
 
 If you are using an older version of BLT that was not installed using Composer, you may update to the Composer-managed version by running the following commands:
 
 1. Remove any dependencies that may conflict with upstream acquia/blt. You may add these back later after the upgrade, if necessary.
 
-  ```
-  composer remove drush/drush drupal/console phing/phing phpunit/phpunit squizlabs/php_codesniffer symfony/yaml drupal/coder symfony/console --no-interaction --no-update
-  composer remove drush/drush drupal/console phing/phing phpunit/phpunit squizlabs/php_codesniffer symfony/yaml drupal/coder symfony/console --dev --no-interaction --no-update
-  composer config minimum-stability dev
-  ```
+        composer remove drush/drush drupal/console phing/phing phpunit/phpunit squizlabs/php_codesniffer symfony/yaml drupal/coder symfony/console --no-interaction --no-update
+        composer remove drush/drush drupal/console phing/phing phpunit/phpunit squizlabs/php_codesniffer symfony/yaml drupal/coder symfony/console --dev --no-interaction --no-update
+        composer config minimum-stability dev
+
 1. (conditional) If you are using Lightning, verify that your version constraint allows it to be updated to the latest stable version:
 
-  ```
-  composer require drupal/lightning:~8 --no-update
-  ```
+        composer require drupal/lightning:~8 --no-update
+
 1. Require acquia/blt as a dev dependency:
 
-  ```
-  composer require acquia/blt:~8 --dev --no-update
-  ```
+        composer require acquia/blt:~8 --dev --no-update
+
 1. Update all dependencies:
 
-  ```
-  composer update
-  ```
+        composer update
+
 1. Execute update script:
 
-  ```
-  ./vendor/acquia/blt/scripts/blt/convert-to-composer.sh
-  ```
+        ./vendor/acquia/blt/scripts/blt/convert-to-composer.sh
+
 
 Note that all of the steps from this point forward are the same steps that would be used by a newly onboarded developer setting up your existing project on their local machine for the first time.
 
@@ -124,16 +108,17 @@ Note that all of the steps from this point forward are the same steps that would
 Before building your project dependencies and installing Drupal, you must have a fully functional \*AMP stack on your local machine. BLT intentionally does not provide this local development environment--that is outside of the scope of BLT’s intended responsibilities. It does, however, make recommendations for which tools you should use to manage your stack.
 
 Please see [Local Development](template/readme/local-development.md) for more information on setting up your \*AMP stack:
-  * [Acquia Dev Desktop](template/readme/local-development.md#using-acquia-dev-desktop-for-blt-generated-projects)
-  * [Drupal VM](template/readme/local-development.md#using-drupal-vm-for-blt-generated-projects)
-  * [Other](https://github.com/acquia/blt/blob/8.x/template/readme/local-development.md#alternative-local-development-environments)
+
+* [Acquia Dev Desktop](template/readme/local-development.md#using-acquia-dev-desktop-for-blt-generated-projects)
+* [Drupal VM](template/readme/local-development.md#using-drupal-vm-for-blt-generated-projects)
+* [Other](https://github.com/acquia/blt/blob/8.x/template/readme/local-development.md#alternative-local-development-environments)
 
 When you have completed setting up your local \*AMP stack, double check that the following pieces of information are still correct:
 
 * Local site DB credentials: `$databases` in docroot/sites/default/settings/local.settings.php
 * Local site URL: `$options[‘uri’]` in docroot/sites/default/local.drushrc.php
 
-## <a name="install"></a>Build your project’s local dependencies and install Drupal locally
+## Build your project’s local dependencies and install Drupal locally
 
 Run the following command from the project root: `blt local:setup`. This will do a lot of things for you, including:
 

mkdocs.yml

@@ -11,24 +11,29 @@ markdown_extensions:
 pages:
   - Home: 'index.md'
   - Overview: 'README.md'
-  - Getting started: 'INSTALL.md'
+  - Getting started:
+    - Installation & upgrade:  'INSTALL.md'
     - Local development: 'template/readme/local-development.md'
-  - Project documentation: 'template/README.md'
+  - Project documentation:
+    - Overview: 'template/README.md'
     - Developer:
           - Onboarding: 'template/readme/onboarding.md'
           - Repository architecture: 'template/readme/repo-architecture.md'
-          - Running project tasks: 'template/readme/project-tasks.md'
+          - Running project tasks:
+            - Overview: 'template/readme/project-tasks.md'
             - Patches: 'template/patches/README.md'
-            - Drush: 'template/drush/README.MD'
-            - Git hooks: 'scripts/git-hook/README.md'
-          - Best practices: 'template/readme/best-practices.md'
+            - Drush: 'template/drush/README.md'
+            - Git hooks: 'template/scripts/git-hooks/README.md'
+          - Best practices:
+            - Overview: 'template/readme/best-practices.md'
             - Views: 'template/readme/views.md'
           - Workflow: 'template/readme/dev-workflow.md'
           - Automated testing: 'template/tests/README.md'
     - Technical Architect:
         - Project architecture document: 'template/readme/architecture.md'
         - Deploying to cloud: 'template/readme/deploy.md'
-        - Release process: 'template/readme/release-process.md'
+        - Releases:
+          - Release process: 'template/readme/release-process.md'
           - Release notes: 'scripts/release-notes/README.md'
         - Setting up continuous integration: 'template/readme/ci.md'
         - Open source contribution: 'template/readme/os-contribution.md'

template/readme/best-practices.md

@@ -4,27 +4,18 @@
 
 _This document is a work in progress._ Unlinked items are planned topics, feel free to contribute.
 
-* [Standards](#standards)
-* [Exporting configuration](#exporting-config)
-* [Configuration updates](#config-updates)
-* [Caching strategies](#caching)
-* [Patching](#patching)
-* [Building Views](#views)
-* [Logging](#logging)
-* [Building content types](#content-types)
-
-## <a name="standards"></a>Standards
+## Standards
 
 All work must conform to established best practices and coding standards. Code quality is ensured in a variety of ways:
 
-* All code must conform to [Drupal Coding Standards](https://www.drupal.org/coding-standards). This is enforced via [local git hooks](../scripts/git-hooks/README.md) and [code checks](../build/ performed during continuous integration.
+* All code must conform to [Drupal Coding Standards](https://www.drupal.org/coding-standards). This is enforced via [local git hooks](../scripts/git-hooks/README.md) and code checks performed during continuous integration.
 * All front end code must follow Drupal Theming Best Practices.
 * All code must be reviewed by a peer or established integrator before being merged into the master branch.
 * All new features must covered by an automated test that mirrors the ticket acceptance criteria.
 
 Please peruse the [examples](examples) directory for examples of various coding best practices.
 
-## <a name="exporting-config"></a>Exporting configuration
+## Exporting configuration
 
 All site functionality should be represented in version-controlled code. This includes all configuration. Drupal configuration is typically exported via [Features](https://www.drupal.org/project/features). 
 
@@ -53,7 +44,7 @@ Common mistakes:
 * Each feature has too many dependencies, so no one feature can be used in isolation, or a single feature becomes impossible to disable. E.g., the "Workflow" feature depends on the "Press Room" feature because it requires field_body which is provided by "Press Room."
 * Features are too granular. E.g., there is a separate feature for each role, a feature contains only a single view, etc.
 
-## <a name="config-updates"></a>Configuration updates
+## Configuration updates
 
 * If a change is happening, that change needs to be documented in code, preferably an update hook. E.g.,
     * Reverting features and feature components `features_revert_module()`
@@ -62,7 +53,7 @@ Common mistakes:
 * Updates needs to be actively monitored. This should be done using NewRelic, SumoLogic, Logstreaming, and/or other monitoring tools.
 * Updates need to be intentional. E.g., don't use cloud hooks or cron jobs to automatically execute updates or clear caches.
 
-## <a name="caching"></a>Caching
+## Caching
 
 Without caching, Drupal is slow. As a general rule of thumb, _try to cache everything that you can_ and _try to invalidate that cache only when it is likely to be stale_. 
 
@@ -89,24 +80,25 @@ Specifically, ensure that you are properly caching data at every level possible,
 
 See the [Drupal 8 Cache API](https://www.drupal.org/developing/api/8/cache) documentation for information in implementing your caching strategy.
 
-## <a name="patching"></a>Patching
+## Patching
 
 All modifications to contributed code should be performed via a patch. For detailed information on how to patch projects, please see [../patches/README.md]
 (../patches/README.md)
 
-## <a name="views"></a>Views
+## Views
 
 Please see [views.md](views.md).
 
-## <a name="logging"></a>Logging
+## Logging
 
-* Any configuration changes from custom modules should be logged to watchdog (also [Acquia Library recommendations|https://docs.acquia.com/articles/how-audit-authenticated-user-actions-better-risk-management])
+* Any configuration changes from custom modules should be logged to watchdog (also [Acquia Library recommendations](https://docs.acquia.com/articles/how-audit-authenticated-user-actions-better-risk-management)
 * Any destructive actions **must** be logged
 
 
-## <a name="content-types"></a>Building content types
+## Building content types
 
 @todo Document:
+
 * Appropriate time to use fields
 * Audit for overly complex content types
     * Reason: All fields loaded for each node load

template/readme/ci.md

@@ -1,4 +1,4 @@
-## <a name="ci"></a> Continuous Integration
+## Continuous Integration
 
 Integration with Travis CI is included, although Phing tasks can be used with any CI tool. The default Travis CI build process is as follows:
 
@@ -21,17 +21,15 @@ Automated testing of live content is easy to set up with two simple steps:
 
 1. Add the hostname of your staging server to .travis.yml:
 
-     ```
-     ssh_known_hosts:
-       - staging-12345.prod.hosting.acquia.com
-     ```
+         ssh_known_hosts:
+           - staging-12345.prod.hosting.acquia.com
+
 2. Override the default `ci:build:validate:test` target by adding the following to `build/custom/phing/build.xml`:
 
-     ```
-     <!-- Override the core ci:build:validate:test target to include a local refresh-->
-     <target name="ci:build:validate:test" description="Builds, validates, tests, and deploys an artifact."
-       depends="validate:all, ci:setup, tests:security-updates, tests:phpunit, local:sync, local:update, tests:behat" />
-     ```
+         <!-- Override the core ci:build:validate:test target to include a local refresh-->
+         <target name="ci:build:validate:test" description="Builds, validates, tests, and deploys an artifact."
+           depends="validate:all, ci:setup, tests:security-updates, tests:phpunit, local:sync, local:update, tests:behat" />
+
 
 ### Setting Up Travis CI for automated deployments
 
@@ -46,31 +44,26 @@ To set up this workflow, you must configure Acquia Cloud, GitHub, and Travis CI
 
 1. Generate an SSH key locally. E.g.,
 
-     ```
-     cd ~/.ssh
-     ssh-keygen -t rsa -b 4096
-     ```
+         cd ~/.ssh
+         ssh-keygen -t rsa -b 4096
 
    Do not use a passphrase!
+
 1. Create a new Acquia Cloud account to be used exclusively as a container for the SSH keys that will grant Travis push access to Acquia Cloud. This can be done by inviting a new team member on the "Teams" tab in Acquia Cloud. You can use an email address like `<email>[email protected]`. The team member must have SSH push access.
 1. Login the your new Acquia Cloud account and add the public SSH key from the key pair that was generated in step 1 by visiting `https://accounts.acquia.com/account/[uid]/security`.
 1. Add the same public SSH key to the "Deployment Keys" section on your project's GitHub settings page, located at `https://github.com/acquia-pso/[project-name]/settings/keys`.
 1. Add the _private SSH key_ to your project's Travis CI settings located at `https://magnum.travis-ci.com/acquia-pso/[project-name]/settings`.
 1. Uncomment the example deployment steps in your .travis.yml file and customize them to deploy your desired branch.
 1. Add your cloud git repository to the remotes section of your project.yml file:
-
-    ```
-    remotes:
-       - [email protected]:example.git`
-    ```
+
+        remotes:
+           - [email protected]:example.git`
 
 1. Add your cloud git repository's server host name to `ssh_known_hosts` in your .travis.yml file.
 
-    ```
-    addons:
-      ssh_known_hosts:
-      - svn-14671.prod.hosting.acquia.com
-    ```
+        addons:
+          ssh_known_hosts:
+          - svn-14671.prod.hosting.acquia.com
 
 1. Commits or merges to the develop branch on GitHub should now trigger a fully built artifact to be deployed to your specified remotes.
 

template/readme/deploy.md

@@ -33,7 +33,7 @@ This task is analogous to `setup:build` but with a few critical differences:
 
 After the artifact is created, you can inspect it or even run it as a website locally. You may also manually commit and push it to ACE.
 
-## <a name="build-artifact"></a>Create and deploy the build artifact
+## Create and deploy the build artifact
 
 To both create and deploy the build artifact in a single command, run the following command