Docs: improve getting started (#1254)

tools/vf-component-library/src/site/_includes/footer.njk

@@ -1,38 +1,80 @@
-<footer class="vf-footer">
+<footer class="vf-footer | vf-search-client-side--no-index">
   <div class="vf-footer__inner">
     <p class="vf-footer__notice">A toolkit to quickly build better life science websites.</p>
     <div class="vf-footer__links-group | vf-grid vf-grid__col-5">
       <div class="vf-links">
         <ul class="vf-links__list | vf-list">
+          <h4 class="vf-links__heading">
+            <a class="vf-heading__link" href="/about">About</a>
+          </h4>
           <li class="vf-list__item">
-            <a class="vf-list__link" href="{{ '/' | url }}">About</a>
+            <a class="vf-list__link" href="{{ '/about/faq' | url }}">FAQ</a>
           </li>
           <li class="vf-list__item">
-            <a class="vf-list__link" href="{{ '/developing' | url }}">Documentation</a>
+            <a class="vf-list__link" href="{{ '/about/roadmap' | url }}">Roadmap</a>
           </li>
           <li class="vf-list__item">
-            <a class="vf-list__link" href="https://join.slack.com/t/visual-framework/shared_invite/enQtNDAxNzY0NDg4NTY0LWFhMjEwNGY3ZTk3NWYxNWVjOWQ1ZWE4YjViZmY1YjBkMDQxMTNlNjQ0N2ZiMTQ1ZTZiMGM4NjU5Y2E0MjM3ZGQ">Help, chat</a>
+            <a class="vf-list__link" href="{{ '/about/consultation' | url }}">Consultation process</a>
           </li>
         </ul>
       </div>
       <div class="vf-links">
         <ul class="vf-links__list | vf-list">
+          <h4 class="vf-links__heading">
+            <a class="vf-heading__link" href="/building">Building</a>
+          </h4>
           <li class="vf-list__item">
-            <a class="vf-list__link" href="{{ '/search' | url }}">Search</a>
+            <a class="vf-list__link" href="{{ '/components' | url }}">Component list</a>
           </li>
           <li class="vf-list__item">
-            <a class="vf-list__link" href="{{ '/components' | url }}">Components</a>
+            <a class="vf-list__link" href="{{ '/patterns' | url }}">Patterns and examples</a>
           </li>
           <li class="vf-list__item">
-            <a class="vf-list__link" href="{{ '/updates' | url }}">Changelog, updates</a>
+            <a class="vf-list__link" href="{{ '/troubleshooting' | url }}">Troubleshooting</a>
+          </li>
+        </ul>
+      </div>
+      <div class="vf-links">
+        <h4 class="vf-links__heading">
+          <a class="vf-heading__link" href="/developing">Developing</a>
+        </h4>
+        <ul class="vf-links__list | vf-list">
+          <li class="vf-list__item">
+            <a class="vf-list__link" href="{{ '/developing/getting-started/setting-up' | url }}">Setting up</a>
+          </li>
+          <li class="vf-list__item">
+            <a class="vf-list__link" href="{{ '/developing/components/creating-new-components' | url }}">Creating a component</a>
+          </li>
+          <li class="vf-list__item">
+            <a class="vf-list__link" href="{{ '/developing/guidelines/user-base' | url }}">User base</a>
+          </li>
+          <li class="vf-list__item">
+            <a class="vf-list__link" href="{{ '/developing/guidelines/css' | url }}">Sass and CSS</a>
+          </li>
+          <li class="vf-list__item">
+            <a class="vf-list__link" href="{{ '/developing/guidelines/javascript' | url }}">JavaScript</a>
+          </li>
+          <li class="vf-list__item">
+            <a class="vf-list__link" href="{{ '/developing/getting-started/pull-requests' | url }}">Making a Pull Request</a>
           </li>
         </ul>
       </div>
       <div class="vf-links">
-        {# <h4 class="vf-links__heading">Category</h4> #}
+        <h4 class="vf-links__heading">
+          Project
+        </h4>
         <ul class="vf-links__list | vf-list">
           <li class="vf-list__item">
-            <a class="vf-list__link" href="{{ '/feed.xml' | url }}">RSS Feed</a>
+            <a class="vf-list__link" href="{{ '/search' | url }}">Search</a>
+          </li>
+          <li class="vf-list__item">
+            <a class="vf-list__link" href="{{ '/updates' | url }}">Changelog, updates</a>
+          </li>
+          <li class="vf-list__item">
+            <a class="vf-list__link" href="https://github.com/visual-framework/vf-core">GitHub</a>
+          </li>
+          <li class="vf-list__item">
+            <a class="vf-list__link" href="https://join.slack.com/t/visual-framework/shared_invite/enQtNDAxNzY0NDg4NTY0LWFhMjEwNGY3ZTk3NWYxNWVjOWQ1ZWE4YjViZmY1YjBkMDQxMTNlNjQ0N2ZiMTQ1ZTZiMGM4NjU5Y2E0MjM3ZGQ">Slack</a>
           </li>
         </ul>
       </div>
@@ -59,6 +101,9 @@
       <span class="vf-footer__legal-text">
         Latest release: <code>{{ siteConfig.vfVersion }}</code> <a href="{{ '/updates' | url }}" class="vf-footer__link">See more releases</a>
       </span>
+      <span class="vf-footer__legal-text">
+        <a class="vf-footer__link" href="{{ '/feed.xml' | url }}">RSS Feed</a>
+      </span>
       <span class="vf-footer__legal-text">
         Code license is Apache 2.0
       </span>

tools/vf-component-library/src/site/about/faq.njk

@@ -34,7 +34,7 @@ layout: layouts/base.njk
 
 ### Is VF Core just a Bootstrap with a different theme?
 
-No. VF Core is an architecture to build extensible components that contain CSS/Sass, JS, Nunjuck templates, and image assets. You could use the VF Core to make a Bootstrap-style framework.
+No. VF Core is an architecture to build extensible components that contain CSS/Sass, JS, Nunjucks templates, and image assets. You could use the VF Core to make a Bootstrap-style framework.
 
 ### I’m a small research team, should I use VF Core?
 
@@ -52,7 +52,7 @@ No. It has a default look out of the box, but it is fully customisable by alteri
 
 No, but yes … do both, if you need to.
 
-This question involve the Visual Framework's architecture which addresses common issues with code sharing and compatibility with life science webistes. This projecft allows you to share Visual Framework components without disrupting your freedom to choose Bootstrap, Foundation, jQuery, React or another framework for the rest of your site.
+This question involve the Visual Framework's architecture which addresses common issues with code sharing and compatibility with life science websites. This project allows you to share Visual Framework components without disrupting your freedom to choose Bootstrap, Foundation, jQuery, React or another framework for the rest of your site.
 
 ### What components are available?
 

tools/vf-component-library/src/site/index.njk

@@ -16,6 +16,9 @@ layout: layouts/base.njk
     <li class="vf-navigation__item">
       <a href="/components" class="vf-navigation__link">Components</a>
     </li>
+    <li class="vf-navigation__item">
+      <a href="/patterns" class="vf-navigation__link">Examples</a>
+    </li>
     <li class="vf-navigation__item">
       <a href="/about/faq" class="vf-navigation__link">FAQ</a>
     </li>
@@ -25,9 +28,9 @@ layout: layouts/base.njk
     <li class="vf-navigation__item">
       <a href="/building" class="vf-navigation__link">Building</a>
     </li>
-    <li class="vf-navigation__item">
+    {# <li class="vf-navigation__item">
       <a href="/developing" class="vf-navigation__link">Developing</a>
-    </li>
+    </li> #}
   </ul>
 </nav>
 
@@ -47,47 +50,65 @@ layout: layouts/base.njk
 {# Installation #}
 <section class="embl-grid embl-grid--has-centered-content">
   {% render '@vf-section-header', {
-    "section_title": "Install, build",
+    "section_title": "Starter packages",
     "id": "install",
     "vf_section__content": [
-      "Install the source Sass and JavaScript files via yarn"
+      "Use an npm starter package for new projects or to graft existing code."
     ]
   } %}
   <div class="vf-content">
-
     {% markdown %}
 
+    Build components into CSS and JS with <a href="https://github.com/visual-framework/vf-build-boilerplate">vf-build-boilerplate</a>:
+
     <pre class="vf-code-example vf-code-example__pre">
-    # <a href="/building/">Use a starter package</a>
+    yarn create <a href="https://github.com/visual-framework/create-vf-project">@visual-framework/vf-project</a> your-new-site-name <a href="https://github.com/visual-framework/vf-build-boilerplate">vf-build-boilerplate</a>
+    </pre>
+
+    <br/>
 
-    ## Build components into CSS and JS
-    yarn create <a href="https://github.com/visual-framework/create-vf-project">@visual-framework/vf-project</a> your-new-site-name vf-build-boilerplate
+    A full static site generator based off 11ty with <a href="https://github.com/visual-framework/vf-eleventy">vf-eleventy</a>:
 
-    ## A full static site generator based off 11ty
-    yarn create <a href="https://github.com/visual-framework/vf-eleventy">@visual-framework/vf-project</a> your-new-site-name
+    <pre class="vf-code-example vf-code-example__pre">
+    yarn create <a href="https://github.com/visual-framework/create-vf-project">@visual-framework/vf-project</a> your-new-site-name <a href="https://github.com/visual-framework/vf-eleventy">vf-eleventy</a>
     </pre>
+    <br/>
 
-    ### Or: add VF components to an existing project
+    [More about the above and further options](building)
+    {% endmarkdown %}
+  </div>
+</section>
 
+<section class="embl-grid embl-grid--has-centered-content">
+  {% render '@vf-section-header', {
+    "section_title": "Pick and choose",
+    "id": "pick",
+    "vf_section__content": [
+      "Install the source Sass and JavaScript files via yarn to an existing project"
+    ]
+  } %}
+  <div class="vf-content">
+
+    {% markdown %}
     {% codeblock 'bash' -%}
     # 1. Add the Sass starter and any components
 
-    yarn add @visual-framework/vf-sass-config @visual-framework/vf-sass-starter @visual-framework/vf-content
+    yarn add @visual-framework/vf-sass-config @visual-framework/vf-sass-starter @visual-framework/vf-content @visual-framework/vf-analytics-google
 
     # 2. Import it in your Sass
 
     @import 'node_modules/@visual-framework/vf-sass-starter/index.scss';
     @import 'node_modules/@visual-framework/vf-content/vf-content.scss';
 
-    # 3. Import an JS modules
+    # 3. Import JS modules
 
-    import { vfGaTrackInteraction } from '@visual-framework/vf-analytics-google/vf-analytics-google.js';
+    import { vfGaTrackInteraction } from 'node_modules/@visual-framework/vf-analytics-google/vf-analytics-google.js';
 
     {%- endcodeblock %}
 
     <br/>
 
-    [Learn more about these templates and other options](building)
+    [Browse all available components](components)
 
     {% endmarkdown %}
 
@@ -100,20 +121,21 @@ layout: layouts/base.njk
     "section_title": "Prebuilt CDN",
     "id": "cdn",
     "vf_section__content": [
-      "If you just need pre-compiled CSS and JS, you can use the CDN."
+      "Get a kitchen sink of pre-compiled CSS and JS from the CDN."
     ]
   } %}
   <div class="vf-content">
 
     {% markdown %}
-    [See examples in our HTML boilerplates](/patterns) for quick starts.
-
     {% codeblock 'html' -%}
     <!-- CSS only -->
     <link rel="stylesheet" href="https://assets.emblstatic.net/vf/{{ siteConfig.vfVersion }}/css/styles.css">
     <!-- JS -->
     <script src="https://assets.emblstatic.net/vf/{{ siteConfig.vfVersion }}/scripts/scripts.js"></script>
     {%- endcodeblock %}
+    <br/>
+
+    [See examples in our HTML boilerplates](/patterns) for quick starts and layouts.
 
     {% endmarkdown %}
   </div>
@@ -137,7 +159,7 @@ layout: layouts/base.njk
 
   {#- show all pages classes as sections -#}
   {#- by default, 11ty sorts by `date` field -#}
-  {%- for section in collections.sections  %}
+  {%- for section in collections.sections | reverse %}
     {% if section.data.is_index == true %}
       {# Eventually these might have unique images, not sure yet #}
       {%- set absolutePostUrl %}{{ metadata.id }}{{ section.url }}{% endset %}

tools/vf-component-library/src/site/patterns/index.njk

@@ -1,6 +1,6 @@
 ---
 is_index: true
-title: Patterns and boilerplates
+title: Examples and patterns
 subtitle: More than components, this is how you should do things.
 intro: Where components offer technical implementations, patterns and boilerplates show how things should come together to facilitate tasks and goals.
 section: patterns

tools/vf-component-library/src/site/troubleshooting/index.njk

@@ -1,16 +1,21 @@
 ---
-title: Problems 🏚 😭
+title: Troubleshooting
 subtitle: Troubleshooting tips for some frequent things that can go wrong.
 date: 2019-04-09 12:24:50
+order: 5
+is_index: false
+section: about
 tags:
+  - about
   - troubleshooting
+  - sections
 layout: layouts/base.njk
 templateEngineOverride: njk
 ---
 
 {% render '@vf-intro', {
   "component-type": "container",
-  "vf_intro_heading": title,
+  "vf_intro_heading": title + " 🏚 😭",
   "vf_intro_lede": subtitle,
   "vf_intro_subheading": "",
   "vf_intro_text": [
@@ -70,7 +75,7 @@ developing `vf-core`, for other projects run `gulp dev`.
 
 ### Rollback your components or `vf-core` version
 
-You might have an incombatibility between component versions or `vf-core`. If
+You might have an incompatibility between component versions or `vf-core`. If
 you've recently updated, rollback version and re-run `gulp dev`. If that fixes
 issues, consult the component `CHANGELOG.md` files or read up on the [`vf-core`
 release notes](https://github.com/visual-framework/vf-core/releases).
@@ -92,6 +97,15 @@ you’ll want to save any local changes first.
 Your local files might be out of sync, stash your local changes elsewhere and
 run `git reset --hard`.
 
+<hr/>
+
+### Git reset, harder 🚨
+
+If you're at a loss, you can discard all untracked files and non-committed edits
+with `git clean -fx`.
+
+This will remove many things including `node_modules`, so you'll need to run `yarn install`.
+
 {% endmarkdown %}
 
 </div>