DocPad - static web

DocPad este un generator de site-uri statice. Pornind de la diverse surse de informații de pe propriul calculator, DocPad le transformă în fișiere statice, .html-uri simple, ce pot fi mai apoi folosite fără a mai fi nevoie de configurații complexe pe server.

Putem renunța în acest fel la .php, la mysql sau la CMS-uri complexe când de cele mai multe ori nici nu este nevoie de așa ceva. dev.ro este creat folosind această platformă și în afară de conținutul propriu zis crearea site-ului a durat foarte puțin.

Avantaje importante:

  • DocPad folosește tehnologii noi, bine adaptate mediului online - nodejs, coffescript
  • extrem de rapid atât în dezvoltare cât și în funcționare
  • consumă puține resurse
  • funcționalitatea se poate extinde cu ajutorul plugin-urilor
  • simplu de învățat cu rezultate în câteva minute

Mai jos voi parcurge pașii necesari pentru crearea unui astfel de site/blog. La finalul articolului veți avea un blog simplu, funcțional.

Instalarea DocPad

În primul rând, pentru DocPad, avem nevoie de Node.js. Mai jos instalăm versiunile default din Ubuntu 14.04. Alte modalități de install pot fi cu ajuturul unui PPA sau a NVM-ului însă pentru ce avem nevoie aici nu este cazul.

sudo apt-get update
sudo apt-get install nodejs
sudo apt-get install npm

Facem update la npm, din repository-ul lui și instalăm DocPad, global.

sudo npm install -g npm
sudo npm install -g docpad

Odată instalarea finalizată putem începe să folosim DocPad.

Crearea inițială a blog-ului:

mkdir blog && cd blog
docpad run

Vom vedea un dialog din care putem alege structura generală a proiectului. Noi vom un site de la zero așa că alegen opțiunea No Skeleton.

Which skeleton will you use? [1-22]
  1.    HTML5 Boilerplate
  2.    HTML5 Boilerplate with Grunt
  3.    HTML5 Boilerplate with Jade and LESS
  4.    Twitter Bootstrap
  5.    Twitter Bootstrap with Jade
  6.    Twitter Bootstrap with Coffeekup
  7.    Kitchensink
  8.    Benjamin Lupton's Website
  9.    DocPad's Website
  10.   Bevry's Website
  11.   Startup Hostel's Website
  12.   NodeChat
  13.   SlidePad
  14.   Slides
  15.   Reveal.js
  16.   Conference Boilerplate
  17.   Zurb Foundation(SASS)
  18.   Meny
  19.   YUI PureCSS
  20.   Zurb Foundation
  21.   Casteasoft Foundation Simple Blog
  22.   No Skeleton

După alegerea opțiunii 22, în cazul nostru, DocPad își va instala dependințele și va afișa locul în care poate fi accesat din browser, http://127.0.0.1:9778/

Cum nu avem încă nici o pagină creată, în browser vom vedea "Not Found". La adăugarea unei pagini serverul va reface automat proiectul fără a fi nevoie de oprirea explicită a acestuia. Serverul îl putem opri cu CTRL+C.

Directorul node_modules conține toate pachetele și modulele necesare funcționării DocPad. Restul fișierelor și directoarelor le vom folosi pentru a configura funcționarea blog-ului.

Cum funcționează DocPad

Fișierul docpad.coffee conține o serie de opțiuni atât pentru proiect cât și pentru plugin-urile folosite de acesta. Tot aici se pot definii funcții ce mai apoi pot fi folosite în site.

Directorul files conție fișierele statice, ce nu vor fi procesate. Când se generează fișierele statice aceste fișiere pur și simplu vor fi copiate. Aici se pot pune diverse librării 3rd-party gen jQuery sau Bootstrap.

Documents este pentru fișierele ce vor fi convertite sau procesate. Procesările se fac în funcție de extensia fisierelor începând cu ultima extensie. Astfel, dacă fișierul se numește exemplu.html.md, fișierul .md(markdown) va fi transformat în .html și va putea fi accesat din browser ca exemplu.html.

Dacă mai multe fișiere din documents au o structură similară putem face un template comun. Acestea vor fi localizate în directorul layouts.

Adăugarea paginii principale

Pagina principală, ca orice alte pagini pot fi create folosind direct html. Pentru a ne ușura totuși munca putem folosi un template language gen Eco, CoffeeKup sau Jade.

Pentru acest proiect am ales Jade pentru că este cel mai folosit dintre cele 3 și cel mai probabil veți găsi cu ușurință multe exemple pe net.

Instalarea plugin-ului de Jade se face prin comanda de mai jos. Intern comanda docpad folosește npm și adaugă automat plugin-ul în package.json. La instalarea proiectului pe un alt calculator rulăm comanda npm install pentru a instala toate plugin-urile folosite.

docpad install jade

După terminarea instalării adăugăm fișierul index.html.jade în src/documents

doctype html
html
    head
        meta(charset='UTF-8')
        title Blog-ul meu
    body
        h1 Blog-ul meu

Acum, la rularea comenzii docpad run, când accesăm http://127.0.0.1:9778/ vom putea vedea pagina html rezultată din conversia acestui fișier .jade.

Adăugarea unui post

Pentru că toate paginile noastre vor avea o structură similară vom construi un layout numit post.html.jade in directorul src/layouts.

doctype html
html
    head
        meta(charset='UTF-8')
        title= document.title
    body
        h1= document.title
        div.content!= content

În plus față de index.jade.html avem variabilele document.title și content. Aceste variabile își vor lua valorile din fișierele cu articolele pe care urmează să le scriem.

Pentru adăugarea paginilor cu articole vom folosi Markdown. Practic vom scrie totul într-un format foarte simplu care va fi automat transformat într-o pagină web.

Instalăm un plugin de Markdown:

docpad install marked

După finalizarea instalării putem crea fișierul hello.html.md în src/documents sau în oricare dubdirector al acestuia.

---
title: Hello Page!
layout: post
---

Titlu
-----

Pagină **exemplu**

Pentru fiecare articol vom avea câte un fișier diferit. layout conține numele template-ului creat mai sus. Diferite articole pot avea payout-uri diferite. Variabila title din acest fișier va putea fi folosită în layout cu document.title.

Tot ce urmează după al doilea "---" va putea fi folosit în layout ca variabila content.

Acest articol va fi accesibil la http://127.0.0.1:9778/hello.html

Lista de post-uri

După crearea unui număr de articole dorim ca acestea să fie accesibile ca link-uri din pagina de index. DocPad ne oferă un set de helpers, funcții ce ne permit diverse tipuri de căutări printre documente. Pentru acest exemplu vom folosi funcția getCollection pentru generarea listei de articole.

Modificăm fișierul index.html.jade astfel:

doctype html
html
    head
        meta(charset='UTF-8')
        title Blog-ul meu
    body
        h1 Blog-ul meu
        h2 Articole
        ul.posts
            each post in getCollection('html').findAll({layout: 'post'}).toJSON()
                li.post
                    a(href='./#{post.url}')= post.title

Practic cerem toate fișierele html și căutăm printre ele pe acelea care în variabila layout au valoarea post. Mai apoi, pentru fiecare articol găsit generăm o înregistrare în listă(ul) cu un link către url-ul articolului. Rezultatul funcției getCollection este un obiect Query-Engine.

Folosirea de tag-uri

Pentru folosirea de tag-uri în blog-ul nostru vom folosi un plugin pentru tag-uri.

docpad install tags

Articolele la care ne dorim această funcționalitate vor conține tag-urile în header:

---
title: Hello Page!
layout: post
tags:
    - hello
    - docpad
    - test
---
Titlu
-----

Pagină **exemplu**

Fără a mai face alte modificări, la executarea docpad run se va genera în directorul out/tags câte un fișier JSON pentru fiecare tag din întreg proiectul.

Pentru a transforma JSON-urile în pagini HTML trebuie să configurăm plugin-ul. Acest lucru se face modificând fișierul docpad.coffee care va arăta astfel:

# DocPad Configuration File
# http://docpad.org/docs/config

# Define the DocPad Configuration
docpadConfig =
    plugins:
        tags:
            extension: '.html'
            injectDocumentHelper: (doc) ->
                doc.setMeta {layout: 'tag'}

# Export the DocPad Configuration
module.exports = docpadConfig

Am schimbat extensia în '.html' și astfel se vor genera fișiere html în loc de json-uri. injectDocumentHelper va fi executată la transformarea documentului și astfel, adăugându-i layout: 'tag' vom transforma fișierul în .html folosind layout-ul tag.

Layout-ul src/layouts/tag.html.jade poate avea următorul conținut:

doctype html
html
  head
    meta(charset='UTF-8')
        title= document.tag
    body
        h1 Blog-ul meu
        h2 Articole cu #{document.tag}
        ul.posts
            each post in getCollection('html').findAll({layout: 'post', tags: {$in: document.tag}}).toJSON()
                li.post
                    a(href='./#{post.url}')= post.title

Practic vom avea o pagină ce conține lista tuturor atricolelor ce conțin un anumit tag. Mai rămâne doar să modificăm index.html.jade pentru a avea și o listă cu toate tag-urile din blog.

doctype html
html
    head
        meta(charset='UTF-8')
        title Blog-ul meu
    body
        h1 Blog-ul meu
        h2 Articole
        ul.posts
            each post in getCollection('html').findAll({layout: 'post'}).toJSON()
                li.post
                    a(href='./#{post.url}')= post.title
        h2 Listă tag-uri
        ul.tags
            each tag in getFilesAtPath('tags/').toJSON()
                li.tag
                    a(href='./#{tag.url}')= tag.title

docpad run va genera acum la http://127.0.0.1:9778/ atât lista articolelor cât și pe cea a tag-urilor.

Pentru funcționalitate mai complexă puteți încerca și Related, TagCloud, sau AssociatedFiles

Găzduirea

Tot ce am lucrat până acum a fost pe propriul calculator însă dacă vrem ca blog-ul să fi accesibil și altora trebuie să-l punem undeva accesibil non stop.

Voi prezenta pe scurt două alternative.

Propriul server/VPS sau Shared Hosting (SSH)

În .env vom pune datele contului unde facem găzduirea:

#!/bin/bash
DEPLOY_SOURCE_DIR="out/"
DEPLOY_DEST_DIR="~/public_html/"
DEPLOY_SERVER=dev.ro
DEPLOY_ACCOUNT=dev

out/ este locul de pe propriul calculator, de unde se vor copia fișierele. Restul liniilor sunt datele legate de serverul destinație, unde vor fi copiate fișierele.

În .deployignore punem tot ce dorim să nu fie copiat pe server.

**.svn
.git
.gitignore

Scriptul de instalare va avea forma:

#!/bin/bash
set -o nounset
set -o errexit

NFLAG=""

while getopts ":n" opt; do
  case $opt in
    n)
      NFLAG="-n"
      ;;
    \?)
      echo "Invalid option: -$OPTARG" >&2
      ;;
  esac
done

# Set the environment by loading from the file "environment" in the same directory
DIR="$( cd "$( dirname $( dirname "$0" ) )" && pwd)"
source "$DIR/.env"

echo "Deploying ${DIR}/${DEPLOY_SOURCE_DIR} to ${DEPLOY_ACCOUNT}@${DEPLOY_SERVER}:${DEPLOY_DEST_DIR}"

docpad generate --env static
chmod -R og+Xr out
rsync $NFLAG -rvzp --delete --exclude-from="$DIR/.deployignore" "${DIR}/${DEPLOY_SOURCE_DIR}" "${DEPLOY_ACCOUNT}@${DEPLOY_SERVER}:${DEPLOY_DEST_DIR}"

De fiecare dată când dorim să punem pe server versiunea locală vom executa bin/deploy.sh.

Ca dezavantaj ar fi faptul că e nevoie de un abonament de găzduire sau de un VPS.
Personal prefer varianta aceasta pentru că-mi oferă mai mult control.
Pot alege o găzduire în România de exemplu, pentru o încărcare mai rapidă sau pentru SEO.

GitHub

GitHub pe lângă faptul că ne permite găzduirea proiectelor git ne dă și posibilitatea de a găzdui pagini statice prin GitHub Pages. Pașii de mai jos presupun că deja aveți un cont pe GitHub și că știți în mare ce este și cum se folosește git-ul.

In primul rând trebuie să excludem anumite fișiere din proiectul git pe care urmează să-l activăm. Fișierul .gitignore trebuie să conțină cel puțin următoarele linii:

node_modules/*
out/*
*.swp

_nodemodules conține pachetele și dependințele pachetelor NPM. Nu avem nevoie de ele pentru că se recrează automat prin rularea comenzii _npm install".

Directorul out conține fișierele statice care de asemenea sunt create automat de fiecare dată când rulăm docpad run.

Următorul pas este să facem un nou proiect pe GitHub ... să-i spunem blog și apoi să inițiem local un repo git și să urcăm blog-ul nostru pe GitHub. clneagu este userul meu pe GitHub și trebuie să-l înlocuiți cu propriul username.

git init
git add .
git commit -m "Initial commit."
git remote add origin git@github.com:clneagu/blog.git
git push -u origin master

Acum avem proiectul pe GitHub și trebuie să activăm pagina pe GitHub Pages. Pentru aceasta ar trebui să compilăm paginile statice și să facem un branch origin/gh-pages cu ele însă pentru simplitate vom folosi un plugin numit ghpages.

docpad install ghpages

Comanda modifică fișierul package.json așa că trebuie să commit-uim și noi modificarea în git. După terminarea instalării mai rămâne de rulat comanda de generare a paginilor statice si de upload pe GitHub Pages.

docpad deploy-ghpages --env static

Comanda va copia paginile statice în branch-ul gh-pages al proiectului.
După câteva minute blogul va fi disponibil la http://clneagu.github.io/blog/

Procedurile la GitHub se mai pot schimba în timp însă puteți găsi detalii updatate la GitHub Pages Basics respectiv GitHub custom domain pentru a găzdui blog-ul sub propriul nume de domeniu.

Concluzie

Pornind de la bazele DocPad prezentate mai sus se pot face ajustări mai mult sau mai puțin cosmetice. Cu siguranță ar ajuta niște CSS-uri și JavaScript-uri :) De asemenea există numeroase plugin-uri sau teme ce pot fi de ajutor. Chiar pe GitHub putem găsi o mulțime de resurse publicate chiar de către DocPad.

Conținutul acestui site reflectă interesele și preferințele autorilor.