Skip to content

Latest commit

 

History

History
121 lines (72 loc) · 5.16 KB

README.md

File metadata and controls

121 lines (72 loc) · 5.16 KB
Raw

WebPlatform

This is the homepage served at www.webplatform.org. We are serving them as non dynamic content due to the fact that we do not need to change the content frequently.

Although this workspace is for the static content of the site, it can also be used to work locally on HTML and CSS markup and patterns for various projects inside WebPlatform Docs.

The pages are generated through a Node.js static site generator called DocPad and allows us to keep edition DRY by not copy-pasting code in many places while allowing us to have static documents to serve. To learn more about DocPad, you can refer to their DocPad documentation.

Installation

NOTE: Directives assumes you are using a Unix like Operating System, but DocPad also works with Microsoft Windows.

  1. Install NodeJS and NPM

    You can download node from nodejs.org.

    As for NPM, it depends of the Operating system you are using. You can see the NPM installation instruction from the nodejs website.

  2. Fork the project, and checkout the code

     mkdir -p ~/workspace/webplatform/www
 cd ~/workspace/webplatform/www
 git clone [email protected]:renoirb/www.webplatform.org.git .
 make dev-deps

    This installs all dependencies to work on the project.

  3. Create a branch and start your work.

     git checkout -b improving-flexbox-markup

  4. Code is managed from the src/ folder, and what gets changed in it gets regenerated automatically by what we call a "watcher", files are regenerated at every changes into out/ folder.

     make dev-local

    You can also leverage work with CSS and JavaScript using built in tools:

    • JavaScript Linting

        make lint

    • Work on assets with live reload

        make dev-local

    • Work on SASS files, open up another tab (leave make dev-local run)

        make dev-compass

    NOTE: Working on CSS, have a look at README.contributing-css.md.

    IMPORTANT: Compass is taking care to compile SASS files from sass/. It is configured to write to src/documents/assets/css/. You can configure Compass to watch files for you and copy them in the src/ folder. Technically DocPad should detect changes in src/documents/ and refresh the equivalent files in out/. Which is not always the case. This will be fixed with issue Fixing DocPad and Compass compilation conflicts

         make generate

    • Testing before pushing to the repository

        make static

    This gives you an equivalent of what gets deployed in production without watchers. It’ll create a local web server to test things out. If you have access to the salt master, you can follow the procedure described in Accessing a VM using SSH and try the website through the proxy it describes. Look at the port number make static gives in the Makefile, use your web browser that you configured the proxy to the address http://salt:9778/.

    • Everything works? Make a pull request from your branch :D

Deploying

  1. Prepare for deploying

     make deps
 make generate

    If you are on the salt master, this can be run from /srv/code/www/repo, then you can use Salt to deploy

     wpd-deploy app

    If you are happy and want to make a dated snapshot of it;

     make package

  2. ... In progress...

    Current plan is that when a person who has rights to merge to master, a deployment system will pull from github, run the scripts in the previous step, sync the files with all web servers. Automatically.

Related

Depdencies

For more details, see package.json file.

Useful documentation

Besides reading the source, I found those pages useful.