Installation & Setup

Installing Concord

There are multiple ways to add Concord to your project. The most common setups are outlined below.

Option 1: Using a Package Manager & Bundler

This option uses your package manager to download Concord, and your project’s existing build tooling to bundle it into the final output. This is the recommended approach if you’re already using these tools.

First, install @jrgermain/concord as a dependency. For example, if you’re using NPM, you’d run the following command:

npm install @jrgermain/concord

Next, in the entry point of your project (typically a file named root, index, or main), add the following import statements:

import "@jrgermain/concord/concord.css"; // Adds CSS styles
import "@jrgermain/concord/concord.js"; // Adds UX enhancements

You might have to fiddle with the imports here. For example, concord.js (which needs to run in the browser) might need to be imported in a different file from concord.css (which can be processed at build time).

Option 2: Manual Installation

This option is useful if you aren’t using a package manager or bundler, or if you’re not using a JavaScript-based tech stack.

First, go to the latest GitHub release. Expand the “Assets” section and download the concord-<version>.zip file.

Next, extract the contents and copy them into your project. Note that the .map files are source maps, and are therefore optional.

Lastly, add a <link> tag and a <script> tag to your document head to reference the files you just copied.

<head>
  ...
  <link
    rel="stylesheet"
    type="text/css"
    href="/path/to/concord.css"
  />
  <script src="/path/to/concord.js" async></script>
  ...
</head>

Page Setup

Your application’s HTML structure should follow this template:

<!DOCTYPE html>
<html lang="en">
  <head>
    <!-- TODO: add remaining head content -->
    <meta name="theme-color" content="#fff" />
    <meta
      name="theme-color"
      media="(prefers-color-scheme: dark)"
      content="#010203"
    />
  </head>
  <body class="app">
    <!-- href must match '.app-content' element id -->
    <a class="skip-link" href="#main-content">
      Skip to Main Content
    </a>
    <header class="app-header">
      <div class="app-header-content">
        <!-- Logo/home link -->
        <div class="app-header-left">
          <a class="app-header-item" href="/">
            <img
              class="app-icon"
              aria-hidden="true"
              src="..."
            />
            <span class="app-title-divider"></span>
            <span class="app-title">App Name</span>
          </a>
        </div>

        <!-- Main navigation (optional) -->
        <div class="app-header-center">
          <a
            class="app-header-item"
            href="/link1"
            aria-current="page"
          >
            Current Link
          </a>
          <a class="app-header-item" href="/link2">
            Other Link
          </a>
          <!-- Optional: add a divider between groups of links -->
          <hr class="app-header-divider" />
          <a class="app-header-item" href="/link3">
            Other Link
          </a>
        </div>

        <!-- Sidebar toggle (automatically hidden if there is no sidebar) -->
        <div class="app-header-right">
          <label
            class="app-header-item app-sidebar-toggle if-app-has-sidebar"
          >
            <input
              type="checkbox"
              title="Toggle navigation"
            />
            <div></div>
            <div></div>
            <div></div>
          </label>
        </div>
      </div>
    </header>
    <div class="app-body">
      <!-- Optional -->
      <aside class="app-sidebar">
        <div class="app-sidebar-content">
          <!-- 1 or more of the following: -->
          <section class="app-sidebar-section">
            <h1 class="app-sidebar-heading">Heading</h1>
            <a class="app-sidebar-item" aria-current="page">
              Current Page
            </a>
            <a class="app-sidebar-item">Other Page</a>
          </section>
        </div>
      </aside>

      <main id="main-content" class="app-content">
        <!-- Your page content goes here -->
      </main>
    </div>
  </body>
</html>