Instructions for setting up Markdoc on NearlyFreeSpeech.Net
This guide gives instructions on how to set up a Markdoc wiki on a NearlyFreeSpeech web hosting account. (This is the method used to host this page.)
The content for the wiki will be kept in a Git repository. Pushing the repository to the webserver will cause the website to be freshly rebuilt.
The instructions assume you are working on a Windows computer; it should be even easier than this if you are using OSX or Linux.
Server side setup
Log into your NearlyFreeSpeech website via SSH and perform the following steps:
- Install Markdoc:
easy_install --user markdoc
- Add this line to the top of your
~/.bashrc
:export PATH=$PATH:$HOME/.local/bin
. (This will putmarkdoc
on yourPATH
.) - Initialise a new, bare, git repository:
git init /home/private/git/mywiki --bare
. Note your choice of directory for later. - Create a shell script called
/home/private/git/mywiki/hooks/post-receive
and paste in the shell script below. - Make the script executable:
chmod +x /home/private/git/mywiki/hooks/post-receive
Content of post-receive
shell script
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | #!/bin/sh # Partially plagiarised from http://majorursa.net/content/using-jekyll-nearlyfreespeechnet # Put Python local packages on the PATH export PATH=$PATH:$HOME.local/bin/ REPONAME=mywiki GIT_REPO=$HOME/git/$REPONAME TMP_GIT_CLONE=$HOME/git/tmp_deploy/$REPONAME PUBLIC_WWW=/home/public/mywiki/ echo "==== Making temporary git clone====" git clone $GIT_REPO $TMP_GIT_CLONE cd $TMP_GIT_CLONE echo "==== Building site ====" markdoc --verbose build echo "==== Beginning rsync ====" rsync -vax --cvs-exclude --delete --ignore-errors --include=.htaccess --exclude=.* .html/ $PUBLIC_WWW/ echo "==== Cleaning up temporary files ====" rm -Rf $HOME/git/tmp_deploy/$REPONAME/.git/objects rm -Rf $HOME/git/tmp_deploy/$REPONAME/.git rm -Rf $HOME/git/tmp_deploy/$REPONAME exit |
Note: if you get an error like...
bash: ./post-receive: /bin/sh^M: bad interpreter: No such file or directory
... when running this (or any) BASH script - it means that your shell script has Windows line endings. Try dos2unix post-receive
to fix that. Refer StackOverflow.
Windows desktop setup
You will work on the website content on your Windows desktop, pushing the changes to the NearlyFreeSpeech.Net server when you are ready to publish the website.
Where terminal commands
are shown, execute these in a cmd.exe
or Powershell window.
- Install Python 2,
pip
, and git. If you use Chocolatey (the Windows equivalent of apt-get) then this is a simple matter of runningcinst python2 pip git
as Administrator. Otherwise, go to the appropriate websites, download the software installers and run them. - Install Markdoc:
pip install markdoc
(as Administrator) - Initialise new wiki:
markdoc.exe init --vcs-ignore git C:\mywiki\
- Goto new wiki:
cd C:\mywiki
- Initialise new git repository:
git init .
- Add git remote:
git remote add nfsn ssh://<username>_<site>@ssh.<servername>.nearlyfreespeech.net:/home/private/git/mywiki/
. Note the trailing slash.nfsn
is a short nickname you will use when pushing to the web host, i.e.git push nfsn
.username
is your NearlyFreeSpeech.net username.sitename
is your NearlyFreeSpeech.net site name./home/private/git/mywiki
is the path to your wiki from Step 2 of the server-side setup, above.
- Create some content, say in
test.md
- Push website up to web host -
git push nfsn
Tips:
- If you set up public-key authentication, you won't have to type your NearlyFreeSpeech.Net password every time you do a
git push nfsn
.
Example output after git push nfsn
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 | C:\Users\lws\Documents\GitHub\morrowind-dnd3.5>git push nfsn Counting objects: 5, done. Delta compression using up to 8 threads. Compressing objects: 100% (3/3), done. Writing objects: 100% (3/3), 1.11 KiB | 0 bytes/s, done. Total 3 (delta 2), reused 0 (delta 0) remote: ==== Making temporary git clone==== remote: Cloning into '/home/private//git/tmp_deploy/morrowind-dnd3.5'... remote: done. remote: ==== Building site ==== remote: markdoc: DEBUG: Running markdoc.build remote: markdoc: DEBUG: Running markdoc.clean-temp remote: markdoc.clean-temp: DEBUG: makedirs /home/private/git/tmp_deploy/morrowi nd-dnd3.5/.tmp remote: markdoc: DEBUG: Running markdoc.sync-html remote: markdoc.sync-html: DEBUG: makedirs /home/private/git/tmp_deploy/morrowin d-dnd3.5/.html remote: markdoc.sync-html: DEBUG: rsync -vaxq --cvs-exclude --delete --ignore-er rors --include=.htaccess --exclude=.* --exclude=_* .tmp/ default-static/ .html/ remote: markdoc.sync-html: DEBUG: rsync completed remote: markdoc: DEBUG: Running markdoc.build-listing remote: markdoc.build-listing: DEBUG: Generating listing for / remote: markdoc.build-listing: DEBUG: cp //_list.html //index.html remote: markdoc.build-listing: DEBUG: Generating listing for /media remote: markdoc.build-listing: DEBUG: cp /media/_list.html /media/index.html remote: markdoc.build-listing: DEBUG: Generating listing for /media/sass remote: markdoc.build-listing: DEBUG: cp /media/sass/_list.html /media/sass/inde x.html remote: markdoc.build-listing: DEBUG: Generating listing for /media/css remote: markdoc.build-listing: DEBUG: cp /media/css/_list.html /media/css/index. html remote: ==== Beginning rsync ==== remote: sending incremental file list remote: ./ remote: index.html remote: media/ remote: media/index.html remote: media/css/ remote: media/css/index.html remote: media/sass/ remote: media/sass/index.html remote: remote: sent 10,279 bytes received 115 bytes 20,788.00 bytes/sec remote: total size is 17,994 speedup is 1.73 remote: ==== Cleaning up temporary files ==== To ssh://lws_lws@ssh.phx.nearlyfreespeech.net:/home/private/git/morrowind-dnd3.5 / e311a6f..c608a32 master -> master C:\Users\lws\Documents\GitHub\morrowind-dnd3.5> |
Tips
Markdoc assumes that you will have the following in your .htaccess
file, to rewrite requests for /page
to /page.html
.
1 2 3 4 5 | Options +MultiViews <FilesMatch "\.html$"> ForceType 'application/xhtml+xml; charset=UTF-8' </FilesMatch> |
Public Key Authentication
TODO: Add instructions for setting up public key auth.