These are the sources for unpoly.com.
If you are looking for the source code of the Unpoly framework, visit github.com/unpoly/unpoly.
- unpoly.com is a static site. It uses Unpoly for its frontend.
- We use Middleman, a static site generator based on Ruby.
- Page sources can be found in
source
. We mostly use ERB templates. - All API references and package overviews are parsed live from the Unpoly source code. See Updating API documentation and How API documentation is parsed.
- There is a symlink pointing to a local copy of the Unpoly source code in
vendor/unpoly-local
. This code is used both to parse the API documentation and to provide the Unpoly JavaScript and stylesheets for the site. See Setting up local development below. - Frontend assets can be found in
source/javascripts
andsource/stylesheets
. They are compiled with Sprockets, there is no Webpack or another bundler. The sprockets integration in Middleman 4 works just like the classic Rails asset pipeline. - Helper functions and Middleman configuration can be found in
config.rb
. - The site is deployed by copying the static build files to unpoly.com. We use Capistrano to build and deploy with a single command. See Deployment.
The API docs for Unpoly functions, selectors, etc. are not maintained in this repo but in documentation comments in unpoly/unpoly. Every API page on unpoly.com will have a Change this page link leading to the underlying comment on GitHub.
When you make a change to an API documentation, make a PR in unpoly/unpoly. Make sure to edit files in lib
and not in dist
. Files in dist
are rewritten with every release.
Accordingly all API references and package overviews are not built as Middleman pages. Instead the info is parsed from documentation comments in the Unpoly source code in vendor/unpoly-local
.
Documentation comments look like this in JavaScript files (.js
):
/*-
Linking to fragments
====================
The `up.link` module lets you build links that update fragments instead of entire pages.
@module up.link
*/
In a CoffeeScript file (.coffee
) they will look like this::
###-
Linking to fragments
====================
The `up.link` module lets you build links that update fragments instead of entire pages.
@module up.link
###
The documentation syntax is inspired by YUIDoc. We added many extensions to that syntax to document events, selectors, etc.
Documentation changes should be picked up by reloading. You probably need to restart your development server when you create a new API reference page.
There is Ruby code in lib/unpoly/guide
that parses documentation comments into an AST-like structure (Unpoly::Guide
namespace).
Middleman proxies have been setup in config.rb
so one Middleman page is dynamically created for each symbol in the API comments.
You can create CodePen-like, interactive examples by adding a folder in the examples
directory.
This is currently only used by the Tutorial.
Examples are limited in that there is no active server component, your example needs to work with static files alone. We should probably move our examples to something like Glitch because of this.
When you rename anything with a URL, e.g. by renaming an API function, please add a RewriteRule
to source/.htaccess
to existing links will keep working.
-
Check out the repo
-
Make sure that the symlink
vendor/unpoly-local
points to a copy of the source codes for the Unpoly framework. By default it is expected that theunpoly
andunpoly-site
repositories are checked out in the same parent folder:projects/ unpoly/ unpoly-site/
-
Make sure you have recent build compiled in
unpoly/dist
. Otherwise runnpm run build
in theunpoly
directory. -
Install the Ruby version from
.ruby-version
-
Install dependencies with
bundle install
-
Start a development server with
bundle exec middleman server
-
Test your changes on
http://localhost:4567
If you're using an editor such as VSCode and have Docker available, you can use the DevContainer configuration provided without requiring any dependencies.
- Checkout
unpoly-site
alongsideunpoly
in the same parent folder (as above). - Open project in VSCode.
- When prompted, choose to Reopen in Devcontainer.
Once inside the DevContainer, use bundle exec middleman server
and bundle exec rspec
as you normally would.
You can use Docker to run the development dependencies and middleman sever.
-
Checkout
unpoly-site
alongsideunpoly
in the same parent folder (as above). -
From inside the
unpoly-site
folder, run the command below.docker compose -p unpoly-site -f .devcontainer/docker-compose.yml run --service-ports app
Once the container is running, you can browse documentation from the outside at https://localhost:4567
This repo should have a lot more tests.
The code that parses documentation comments has a few tests in spec
.
Run them with bundle exec rspec
.
There are no E2E tests for the site itself. We should have feature specs with Capybara for that.
- Commit and push changes in
unpoly-site
. - Commit and push changes in
unpoly
, which you might have changed while reviewing the documentation output. - Run
bundle exec cap latest deploy
to push the changes to https://unpoly.com. Static files will be built during deployment.