Athena Framework

A front-end web framework for UCF websites and applications. Developed and maintained by UCF Web Communications.

Quick Links

• Framework Documentation
• Development
• Contributing
• License

Development

These instructions are for installation and development of the project for core development of the Athena Framework. If you're looking for instructions for installing and using the framework in your project, see our documentation.

Installation requirements

• Node.js 5.6.0+
• gulp-cli 2.0.0+

Installation instructions

1. Clone the framework repository onto your machine:

   git clone [email protected]:UCF/Athena-Framework.git

2. Navigate to the root Athena-Framework/ directory and install dependencies:

   cd Athena-Framework/

   npm install

3. (Optional) Create a copy of gulp-config.template.json, modify settings as needed for your local development environment (available options are listed below), and save as gulp-config.json.

4. Run an initial full build of the framework, documentation, and examples:

   gulp setup

That's it! Once you've finished all those steps, the root directory of the repo should look like this:

 ├── _docs/
 ├── _examples/
 ├── dist/
 ├── docs/
 ├── docs-local/
 ├── examples/
 ├── node_modules/
 ├── src/
 └── ...

(We're excluding git-related files in this example, as well as your gulp-config.json and the top-level config files that should have been cloned down from the project on Github, such as gulpfile.js and package.json).

Here's a rundown of what's in each of these directories:

_docs/

Contains source files for the framework's documentation. Athena's docs are built on 11ty, a Node-based static site generator, meaning that they consist primarily of Markdown files.

Documentation files get built to one of two locations: docs-local/ or docs/. docs/ contains production-ready files intended to be served via Github Pages, and requires some unique options that we can't use for local testing. Because of this, the documentation site will only get built to docs/ when Athena's maintainers publish a new tag. If you're working on updates to Athena's documentation, you'll always build changes to docs-local/.

_examples/

Contains source files for local example pages that you can use to test changes to the framework against. Like the framework docs, these framework pages are built on 11ty (but they are totally separate 11ty instances.)

The examples site will get built to examples/.

dist/

Contains distributable framework files, including fallback fonts, minified CSS, and minified JS.

docs/

Contains production-ready documentation files to be served on Github Pages. These files should never be edited directly or be included in commits to the repo--they'll only ever get changed by Athena's maintainers when a new release of the framework is published.

docs-local/

Contains your local copy of the built-out documentation site.

This directory is included in our .gitignore, so only changes to the source files (in _docs/) are tracked via git.

examples/

Contains built-out static site files for Athena's example pages, which are intended to be used for testing changes to the framework's core CSS and JS.

The examples/ directory is included in our .gitignore, so the examples site will never be committed to the main repo--the site exists strictly for local testing.

node_modules/

Contains project dependencies installed via npm.

src/

Contains the primary source files for the framework, including font files, Sass, and JavaScript.

Framework development workflow

The Athena Framework comes with an extensive set of gulp tasks, which we use as the primary means of automating repetitive tasks, such as minification, concatenation, and moving of files.

Your general workflow when working on the Athena Framework will look something like this:

1. Download + install the framework. Run gulp setup once before running watch tasks for the first time.
2. Run gulp watch to watch changes to Sass and JS files in src/, and automatically perform CSS and JS build steps whenever changes are made. Changes to example pages are also watched with this task.
3. When making changes to the docs, run gulp docs-watch to watch changes to files in _docs/ and rebuild your local copy of the documentation into docs-local/.

Gulp tasks are set up to save minified, distributable framework assets in dist/. Whenever you're committing changes to the framework, you should always include updated dist/ files in your commits.

However, documentation-related gulp tasks do not save distributable files to a tracked folder in the repo (docs-local/ is intentionally included in the project's .gitignore file). Commits for documentation-related changes should only include changes to files in _docs/; changes to production-ready documentation files (in docs/) are only made when new tags are released.

Gulp config options

Some key settings used in the framework's gulpfile are configurable via your gulp-config.json file. Available settings and their default values are listed below:

Gulp tasks

Our gulpfile contains a lot of functions and tasks--however, you likely won't (and probably shouldn't) use most of them directly. Listed below are the tasks you'll need to know about when working on the framework:

Contributing

We highly encourage feedback and suggestions from the UCF web development community. If you'd like to submit a feature request or known bug, check out our contributing guidelines.

License

The Athena Framework is released under the MIT License. Included third-party assets (such as webfonts and JavaScript libraries) may be released under separate licenses.

Documentation for the Athena Framework is released as a derivative of Bootstrap 4 alpha.6's documentation under Creative Commons.