Eleventy LibDoc

Eleventy LibDoc is an easy to use and content focused starter project for Eleventy to craft slick and responsive documentation. It was was developed with accessibility awareness and low-tech mindset which allows to reach good page speed performances. It contains vanilla JS self-made components like search, primary navigation, table of content, code highlighting and sandboxes. Every page created with LibDoc is printable and can work properly even without Javascript by maintaining only essential features.

Getting started

1. Clone or fork https://github.com/ita-design-system/eleventy-libdoc
2. Run npm install
3. Enter your own settings in settings.json. Configuration.
4. Build and serve npx @11ty/eleventy --serve or just build npx @11ty/eleventy (if you already have your own web server).

Key features

Configuration

Start entering your own settings into settings.json at the root of the project. Configuration documentation.

• Language configuration
  Every UI text string of Eleventy LibDoc is identified as a key which allows to easily extend it with more languages.
• Site title and description
  Involved in SEO, site title and description take part of the most important settings to be set at project start.
• Site logo configuration
  Optionally replace text link by logo image.
• Author configuration.
  Choose to display or not a default author on each page. Override this setting on each page created.
• Favicon URL
  Set your own favicon, overridable on each page created.
• Custom links configuration
  Into the primary navigation, display important links that visitors may need to see on each page you create.
• Open Graph Image configuration.
  Set the image displayed when visitors share your pages.
• Table of Content configuration
  When content amount is greater than a threshold, a table of content is displayed into page header.
• Floating table of content
  In addition of main TOC, a floating table of content appears when visitor scrolls. Just like main TOC, the floating TOC displays anchor links to headings and also current visible part of the page.
• HTML Base configuration.
  Allows to deploy your build into a sub domain instead of root. Computes input path and every URL to fit to the sub domain target.
• Syntax highlighting configuration
  Adjust your own supported languages for syntax highlighting.
• Edit this page link
  Sets the git root directory project’s URL to enable "Edit this page" button link.

Creating content

Easily write documentation with Markdown and HTML.

• Markdown
  Perfect to write content with common semantics.
• Inline HTML
  Allows to enhance markdown unsupported semantics.
• Widgets
  Useful for advanced and specific usages.
  • Alerts
    Shortcodes and plain HTML that allows to display informations to highlight.
  • Buttons
    Form buttons and links to create Call To Actions.
  • Definition lists
    How to use definition lists.
  • Details and accordion
    Create simple dropdown toggle and accordions.
  • Embeds
    Code integration results of various content providers.
  • Icons
    Available icons to use with the content.
  • Icon cards
    Easily highlight something important in a simple way with an icon, a main text and its description.
  • Images
    Ready to use HTML to highlight your images.
  • Sandboxes
    Simple HTML resources separated from LibDoc’s pages scope and embedded into a LibDoc page.
• Tags
  Assign keywords into your pages to create topics.
• Blogging
  Each page tagged with post is displayed into a blog feed.

Primary navigation

One of the most important element of the user interface. Primary navigation documentation

• Home page link
  Always visible, redirects to the root of the project.
• Search input
  Quickly get search results from any text query entered into the input search form.
• Search occurrences
  Easily navigate into a page clicked from a search result.
• Eleventy Navigation
  Organize your content with infinite-depth hierarchical navigation.
• Eleventy breadcrumb
  Automatic breadcrumb is created from Eleventy navigation.

Files tree

• _data/
  ⤷ Eleventy data global
  • libdocConfig.js
    ⤷ returns default or user defined LibDoc parameters.
    Learn more in configuration
  • libdocFunctions.js
    ⤷ manages filters, shortcodes, collections, widgets, etc.
  • libdocMessages.json
    ⤷ contains i18n strings for user interface.
    Learn more in languages
  • libdocSystem.json
    ⤷ contains non user related parameters.
  • libdocUtils.js
    ⤷ contains helpful and ready to use UI and content functions.
• _includes/
  ⤷ Eleventy directory for includes. Learn more at includes
  • libdoc_before_html.liquid
    ⤷ prepares variables to display before writing HTML.
  • libdoc_breadcrumb.liquid
    ⤷ markup for breadcrumb.
  • libdoc_page.liquid
    ⤷ the most important template to create pages
  • sandbox.liquid
    ⤷ the dedicated template for sandboxes
• assets/
  ⤷ Dedicated user directory for static files like CSS, JS, images etc. Any file into this directory is copied into the build folder. Learn more about passThroughCopy
• core/
  ⤷ LibDoc system directory for UI layouts and assets.
  • assets/
    ⤷ Directory containing all CSS, JS and font files to make LibDoc user interface working properly.
    • js/
    • fonts/
    • css/
  • libdoc_blog.liquid
    ⤷ blog related layout. Learn more about blogging
  • libdoc_search_index.liquid
    ⤷ builds search index JSON file.
  • libdoc_search.html
    ⤷ layout dedicated to search results.
  • libdoc_tag.liquid
    ⤷ layout that displays a list of pages tagged with a specific tag.
  • libdoc_tags.liquid
    layout that displays the list of all tags available into your content.
• sandboxes/
  ⤷ Dedicated user directory for file sandboxes
• .eleventy.js
  ⤷ Eleventy config file. Learn more about configuration
• .eleventyignore
  ⤷ File and directories not to process in Eleventy. Learn more how to ignore files
• .gitignore
  ⤷ Files and directories to ignore in Git.
• favicon.png
  ⤷ Default favicon file. Learn more about favicon
• package-lock.json
  ⤷ Node package file.
• package.json
  ⤷ Node package file.
• settings.json
  ⤷ Project settings. Learn more about configuration