diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..f48c95f8 --- /dev/null +++ b/Makefile @@ -0,0 +1,109 @@ +## Optional Makefile: only used for testing & maintainer automation; +## not used to build live site + +S=@ ## Silent: only print errors by default; + ## run `make S='' [other args]` to print commands as they're run + +## Old versions of jekyll must not call "build". If you have one of +## these versions, either run make like this: make JEKYLL_COMMAND=jekyll +## or create the JEKYLL_COMMAND environmental variable: +# echo 'export JEKYLL_COMMAND=jekyll' >> ~/.bashrc +# exec bash +# make +JEKYLL_COMMAND ?= "bundle exec jekyll build" +SITEDIR=_site +JEKYLL_LOG=._jekyll.log + +####################### +## REGULAR ARGUMENTS ## +####################### + +## `make` (no arguments): just build +default: build + +## `make test`: don't build, but do run all tests +test: pre-build-tests post-build-tests + +## `make valid`: build and run fast tests +valid: pre-build-tests-fast build post-build-tests-fast + +## `make all`: build and run all tests +all: pre-build-tests build post-build-tests + + + +## Pre-build tests which, aggregated together, take less than 5 seconds to run on a typical PC +pre-build-tests-fast: check-for-non-ascii-urls + +## Post-build tests which, aggregated together, take less than 5 seconds to run on a typical PC +post-build-tests-fast: check-for-build-errors ensure-each-svg-has-a-png check-for-liquid-errors \ + check-for-missing-anchors check-for-broken-markdown-reference-links + +## All pre-build tests, including those which might take multiple minutes +pre-build-tests: pre-build-tests-fast + @ true + +## All post-build tests, including those which might take multiple minutes +post-build-tests: post-build-tests-fast + @ true ## SOMEDAY: use linkchecker to find broken links + @ ## after this bug is fixed: https://github.com/wummel/linkchecker/issues/513 + + + + + +################# +## SUB-TARGETS ## +################# +ERROR_ON_OUTPUT="sed '1s/^/ERROR:\n/' | if grep . ; then sed 1iERROR ; false ; else true ; fi" + +## Always build using the default locale so log messages can be grepped. +## This should not affect webpage output. +build: + $S export LANG=C.UTF-8 ; eval $(JEKYLL_COMMAND) 2>&1 | tee $(JEKYLL_LOG) + + +## Jekyll annoyingly returns success even when it emits errors and +## exceptions, so we'll grep its output for error strings +check-for-build-errors: + $S egrep -i '(error|warn|exception)' $(JEKYLL_LOG) \ + | eval $(ERROR_ON_OUTPUT) + + +## Old browser support requires each SVG image also be available as a +## PNG with the same base name +ensure-each-svg-has-a-png: + $S find $(SITEDIR)/img -name '*.svg' | while read file \ + ; do test -f $${file%.svg}.png || echo "$$file missing corresponding PNG" \ + ; done | eval $(ERROR_ON_OUTPUT) + + +## Some Jekyll errors leave error messages in the text +check-for-liquid-errors: + $S grep -r 'Liquid syntax error:' $(SITEDIR)/ | eval $(ERROR_ON_OUTPUT) + + +## Report missing anchors for local links defined in the references file. +# +## Takes less than 1 second here as of 2014-05-16 -harding +check-for-missing-anchors: + $S sed -n 's!^\[[^]]*]: \+!!; s/ .*//; /#/s!^/!!p' _includes/references.md \ + | sort -u \ + | while read link ; do file="$(SITEDIR)/$${link%#*}.html" \ + ; anchor="$${link##*#}" \ + ; egrep -ql '(id|name)=.'$$anchor'[^a-zA-Z0-9_-]' $$file \ + || echo "$$file#$$anchor not found" \ + ; done | eval $(ERROR_ON_OUTPUT) + +check-for-broken-markdown-reference-links: +## Report Markdown reference-style links which weren't converted to HTML +## links in the output, indicating there's no reference definition + $S find $(SITEDIR) -name '*.html' | xargs grep '\]\[' | eval $(ERROR_ON_OUTPUT) + +check-for-non-ascii-urls: +## Always check all translated urls don't contain non-ASCII +## characters or spaces. + $S find _translations -name '*.yml' | while read file \ + ; do grep -H . $$file | sed -n -e '/url:/,$$p' \ + | grep -P '[^\x00-\x7f]|[a-z\-] [a-z\-]' \ + ; done | eval $(ERROR_ON_OUTPUT) diff --git a/README.md b/README.md index ad1d6bf3..c82814bc 100644 --- a/README.md +++ b/README.md @@ -95,6 +95,30 @@ from _site/ to the root of your web server. If you have no web server, run http://127.0.0.1:4000/. This server requires you to add a trailing ".html" by hand in your browser address bar. +#### Building With Make + +After you've installed Jekyll and the other depenencies, you can +optionally use GNU Make to automatically build the site and run several +tests. You will first need to install Make using your package manager; +for example: + + sudo apt-get install make + +Then in your local bitcoin.org repository, run one of the following +commands: + + ## To just build the site, the equivalent of: bundle exec jekyll build + make + + ## After you build the site, you can run all of the tests (may take awhile) + make test + + ## Or you can build the site and run some quick tests with one command: + make valid + + ## Or build the site and run all tests + make all + ## Developer Documentation Each part of the documentation can be found in the [_includes](https://github.com/bitcoin/bitcoin.org/tree/master/_includes) diff --git a/_config.yml b/_config.yml index 3077180c..9abd385f 100644 --- a/_config.yml +++ b/_config.yml @@ -134,6 +134,7 @@ plugins: ./_plugins exclude: - Gemfile - Gemfile.lock + - Makefile future: true lsi: false diff --git a/img/bubble.png b/img/bubble.png new file mode 100644 index 00000000..481bec3c Binary files /dev/null and b/img/bubble.png differ diff --git a/img/bubbleinfo.png b/img/bubbleinfo.png new file mode 100644 index 00000000..d83fb147 Binary files /dev/null and b/img/bubbleinfo.png differ diff --git a/img/bubblewarn.png b/img/bubblewarn.png new file mode 100644 index 00000000..5ac71d53 Binary files /dev/null and b/img/bubblewarn.png differ