├── .gitignore ├── Dockerfile ├── LICENSE ├── Makefile ├── circle.yml ├── docs └── index.md ├── gh-pages ├── circle.yml └── index.html ├── mkdocs.yml ├── scripts ├── circleci-cmd └── deploy └── theme ├── base.html ├── content.html ├── css ├── base.css ├── bootstrap-custom.min.css ├── font-awesome-4.4.0.min.css └── highlight.css ├── fonts ├── FontAwesome.otf ├── fontawesome-webfont.eot ├── fontawesome-webfont.svg ├── fontawesome-webfont.ttf ├── fontawesome-webfont.woff └── fontawesome-webfont.woff2 ├── img └── favicon.ico ├── js ├── base.js ├── bootstrap-3.0.3.min.js ├── highlight.pack.js └── jquery-1.10.2.min.js ├── nav.html └── toc.html /.gitignore: -------------------------------------------------------------------------------- 1 | site 2 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | FROM gliderlabs/alpine:3.2 2 | RUN apk --update add python curl py-pip bash openssh-client git \ 3 | && pip install --upgrade mkdocs \ 4 | && git config --global user.email "team@gliderlabs.com" \ 5 | && git config --global user.name "Gliderbot" \ 6 | && ln -s /root /home/ubuntu \ 7 | && curl -Ls https://github.com/gliderlabs/sigil/releases/download/v0.3.2/sigil_0.3.2_Linux_x86_64.tgz \ 8 | | tar -zxC /bin 9 | ADD ./scripts/* /bin/ 10 | ADD ./gh-pages /tmp/gh-pages 11 | ADD ./theme /pagebuilder/theme 12 | WORKDIR /work 13 | EXPOSE 8000 14 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2015 Glider Labs 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | 23 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | 2 | build: 3 | docker build -t gliderlabs/pagebuilder . 4 | 5 | serve: 6 | docker run --rm -it -p 8000:8000 -v $(PWD):/work gliderlabs/pagebuilder mkdocs serve 7 | -------------------------------------------------------------------------------- /circle.yml: -------------------------------------------------------------------------------- 1 | machine: 2 | services: 3 | - docker 4 | 5 | dependencies: 6 | override: 7 | - docker build -t gliderlabs/pagebuilder . 8 | 9 | test: 10 | override: 11 | - /bin/true 12 | 13 | deployment: 14 | master: 15 | branch: master 16 | commands: 17 | - eval $(docker run gliderlabs/pagebuilder circleci-cmd) 18 | - docker login -e $DOCKER_EMAIL -u $DOCKER_USER -p $DOCKER_PASS 19 | - docker push gliderlabs/pagebuilder 20 | 21 | general: 22 | branches: 23 | ignore: 24 | - gh-pages 25 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | # Pagebuilder 2 | 3 | [](https://circleci.com/gh/gliderlabs/pagebuilder) 4 | 5 | This is the tool Glider Labs uses to generate and deploy project documentation. 6 | 7 | * Built around [MkDocs](http://www.mkdocs.org/) for generating sites based on Markdown 8 | * Deploys to Github Pages under sub-directories for versioning 9 | * Automation and UI to keep and expose docs for other branches and old releases 10 | * Centralizes theming and layout across all projects 11 | * Packaged as a lightweight Docker container usable from anywhere 12 | * Drop-in command to use from CircleCI without messy scripts 13 | 14 | Make documentation for your project following the instructions for [MkDocs](http://www.mkdocs.org/). Namely, 15 | creating a `docs` folder for Markdown and a `mkdocs.yml` file at the project root. 16 | 17 | ## Configuration 18 | 19 | The only extra configuration Pagebuilder expects in `mkdocs.yml` is: 20 | 21 | ```yaml 22 | theme_dir: /pagebuilder/theme 23 | ``` 24 | You should also set `site_url` to the URL of the base of the deployment for the 25 | version dropdown to work correctly. 26 | 27 | ## Previewing 28 | 29 | You can preview your docs with Pagebuilder in Docker. Running from project root: 30 | 31 | ```bash 32 | $ docker run --rm -p 8000:8000 -v $PWD:/work gliderlabs/pagebuilder mkdocs serve 33 | ``` 34 | 35 | ## CircleCI 36 | 37 | Add a deployment command to your `circle.yml` to build and publish the docs 38 | with every build. Here is an example: 39 | 40 | ```yaml 41 | deployment: 42 | master: 43 | branch: master 44 | commands: 45 | - eval $(docker run gliderlabs/pagebuilder circleci-cmd) 46 | ``` 47 | 48 | This is a convenience wrapper that automates all the extra Docker flags needed to 49 | allow pushing the built site to `gh-pages` branch of the repo. 50 | 51 | You need to run this command for every branch you want to build docs for. If 52 | you want to use a branch other than `master` to be used for the `latest` docs, 53 | specify it with `MASTER` environment variable. Here is how you would tell it to 54 | use `release` for latest. It will still make a `release` directory on Github Pages, 55 | but the `latest` directory will be a copy of it. 56 | 57 | ```yaml 58 | deployment: 59 | master: 60 | branch: master 61 | commands: 62 | - eval $(docker run -e MASTER=release gliderlabs/pagebuilder circleci-cmd) 63 | ``` 64 | -------------------------------------------------------------------------------- /gh-pages/circle.yml: -------------------------------------------------------------------------------- 1 | general: 2 | branches: 3 | ignore: 4 | - gh-pages 5 | -------------------------------------------------------------------------------- /gh-pages/index.html: -------------------------------------------------------------------------------- 1 | 2 |
3 | 6 | 10 | 11 | 12 | -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: Pagebuilder 2 | site_url: https://gliderlabs.com/pagebuilder 3 | repo_url: https://github.com/gliderlabs/pagebuilder 4 | dev_addr: 0.0.0.0:8000 5 | theme_dir: /pagebuilder/theme 6 | google_analytics: ['UA-58928488-1', 'auto'] 7 | -------------------------------------------------------------------------------- /scripts/circleci-cmd: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | echo "docker run -v /home/ubuntu/.ssh:/tmp/ssh -v \$PWD:/work -e MASTER=$MASTER -e TAG=$TAG gliderlabs/pagebuilder deploy \"build \$CIRCLE_BUILD_NUM\"" 3 | -------------------------------------------------------------------------------- /scripts/deploy: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | set -ex 3 | 4 | branch="$(git rev-parse --abbrev-ref HEAD)" 5 | master="${MASTER:-master}" 6 | tag="$TAG" 7 | 8 | cp -r "$PWD" /tmp/project 9 | mkdocs build 10 | cp -r site /tmp/site 11 | 12 | if [[ -d /tmp/ssh ]]; then 13 | rm -rf /root/.ssh 14 | cp -r /tmp/ssh /root/.ssh 15 | chown -R root /root/.ssh 16 | fi 17 | 18 | if ! git fetch --depth=1 origin gh-pages; then 19 | git checkout --orphan gh-pages 20 | git rm --cached -rf . 21 | cp /tmp/gh-pages/* . 22 | ls -1 /tmp/gh-pages | xargs git add 23 | else 24 | git stash # removes any changed files 25 | git checkout --track origin/gh-pages 26 | fi 27 | 28 | rm -rf "$branch" 29 | mv /tmp/site "$branch" 30 | git add "$branch" 31 | 32 | if [[ "$branch" == "$master" ]]; then 33 | rm -rf latest 34 | cp -r "$branch" latest 35 | git add latest 36 | if [[ -f latest/homepage.html ]]; then 37 | git mv latest/homepage.html index.html 38 | else 39 | rm -rf index.html 40 | cp /tmp/gh-pages/index.html . 41 | git add index.html 42 | fi 43 | latest="$branch" 44 | fi 45 | 46 | if [[ "$tag" ]]; then 47 | rm -rf "$tag" 48 | cp -r "$branch" "$tag" 49 | git add "$tag" 50 | if [[ "$branch" == "$master" ]]; then 51 | latest="$tag" 52 | fi 53 | fi 54 | 55 | if [[ "$latest" ]]; then 56 | export LATEST="$latest" 57 | sigil -i \ 58 | '{"latest": "{{ var "LATEST" }}", "versions": ["{{ dirs "." | drop "latest" | drop ".git" | drop "site" | drop "build" | join "\", \"" }}"]}' \ 59 | > versions.json 60 | git add versions.json 61 | fi 62 | 63 | if git commit -m "$1"; then 64 | git push origin gh-pages:gh-pages 65 | fi 66 | -------------------------------------------------------------------------------- /theme/base.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | {% if page_description %}{% endif %} 9 | {% if site_author %}{% endif %} 10 | {% if canonical_url %}{% endif %} 11 | {% if favicon %} 12 | {% else %}{% endif %} 13 | 14 |t |