https://github.com/foundation/foundation-docs
Common templates and utilities for the Foundation family documentation.
https://github.com/foundation/foundation-docs
Last synced: about 1 year ago
JSON representation
Common templates and utilities for the Foundation family documentation.
- Host: GitHub
- URL: https://github.com/foundation/foundation-docs
- Owner: foundation
- License: mit
- Created: 2015-12-14T19:24:47.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2024-09-26T21:13:11.000Z (almost 2 years ago)
- Last Synced: 2025-04-05T07:32:59.823Z (about 1 year ago)
- Language: JavaScript
- Size: 3.32 MB
- Stars: 30
- Watchers: 30
- Forks: 24
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Foundation Docs
[](https://travis-ci.org/foundation/foundation-docs)
This is a set of HTML templates and JavaScript utilities shared by the documentation pages for the [Foundation](https://get.foundation) family of frameworks, including:
- [Foundation for Sites](https://get.foundation/sites)
- [Foundation for Emails](https://get.foundation/emails)
## Table of Contents
- [Installation](#installation)
- [JavaScript Usage](#javascript-usage)
- [Sass Usage](#sass-usage)
- [Testing](#testing)
## Installation
This codebase isn't on npm, but this Git repository can be referenced in a `package.json`:
```bash
{
"dependencies": {
"foundation-docs": "foundation/foundation-docs"
}
}
```
## JavaScript Usage
When you `require()` the `foundation-docs` library, you get access to a handful of JavaScript libraries, as well as file paths to HTML templates.
### foundationDocs.handlebars
An instance of a custom Handlebars renderer with all the helpful functions we need to generate documentation.
### foundationDocs.marked
An instance of a custom Marked renderer, which has two custom functions:
- When headings are written, an anchor icon is added to the left of the heading text.
- When code samples are written:
- If the language is `html_example`, a live rendering of the HTML in the sample is added.
- If the language is `inky_example`, a live rendering of the HTML in the sample—within an iframe that loads the Ink CSS—is added.
### foundationDocs.componentTemplate
A String path to the HTML template used for component pages. The general structure is:
- Title area
- Main docs (converted Markdown)
- Sass reference
- JavaScript reference
- Table of contents
The path is `node_modules/foundation-docs/templates/component.html`.
## Sass Usage
The CSS used for the Foundation documentation is included as a series of Sass partials. Foundation and Motion UI must be loaded manually before it.
```scss
@import 'foundation';
@import 'motion-ui';
@include foundation-everything;
@include motion-ui-transitions;
@import 'foundation-docs';
```
## Testing
There are two kinds of tests in the repository:
- **Unit tests**, which are run with Mocha.
- **Visual tests**, which are full HTML templates with all of the documentation UI elements.
Run `npm test` to run the test suite, as well as a BrowserSync server pointing to the visual tests. You can make changes to the HTML, Sass, or JavaScript of the library and see the changes refresh live. Use this test environment to make changes to the documentation template.
### Testing with Foundation
To test with an actual framework's documentation, you can hook the two folders together using `npm link`.
Let's assume you have `foundation-sites` and `foundation-docs` in the same folder:
```
- sites/
- foundation-sites/
- foundation-docs/
```
While inside of the `foundation-sites/` folder, run `npm link ../foundation-docs`. Now Foundation's documentation will reference the changes you're making.