Markdown website generator
A simple Markdown-to-HTML website generator, based on Markdown files and Git.
https://gitlab.com/Castro0o/website_generator
Its central idea is to spare editors from having to done with any conversions, scripts, or HTML. Simply edit the markdown files, git add -
, git commit -m "my edits"
, git push
. A git's post-receive-hook in the website's server will trigger the conversations and scripts which generate the website from the markdown files. Locally there are no dependencies, except Git.
For Editors
Important files and folders:
pages/
contains- sub-folders: which result in website sections
- .md (Markdown) files: which result in website (.html) pages
media/
contains the website media: images, videos, and audio fileslib/
contains .css and .js files
How to:
Create or edit an page: * create/edit only Markdown files (.md) inside the sub-folders from the pages
folder. * Use plain text editor for editing: e.g. Sublime Text, gedit, Brackets, etc. Word-processors such as Word or Mac text editor are unsuitable as they will add formatting information to the text, which we don't want. All formatting should be done explicitly using Markdown (and/or HTML)! * Avoid using spaces in file names.
Add metadata: The website generator requires the inclusion, in each page, of a metadata block. Add it, by using the following YAML example block at the top of each page:
--- category: Blog date: '20160816' title: Permutations1 ...
- category: is usually the same name as the folder the page is in
- date: in the form
yyyymmdd
- title: title of the page
Add images: * store your image in the folder media/
* include it in an article by using the markdown syntax for images: 
* the image location will always begin with media/
, follow by the image name * i.e. 
Publish From within this folder run git add --all
to add all new or modified files
Create a commit git commit --message="describing what change in this commit"
Push commit to repository (AKA publish) git push origin
origin will be the git the server that stores the website and performs the necessary conversions.
For Designers & Developers
Dependencies:
Git Hooks
A Git post-receive hook is used to run the generate_website.py
, when a git commit is pushed to server.
In order to get the post-receive-hook
to perform that task, a few steps need to be taken:
Steps
Locally:
- clone this repository
git clone https://Castro0o@gitlab.com/Castro0o/website_generator.git
- Go to
website_generator.git
directory:cd website_generator.git
- Remove git folder and .gitignore folder:
rm -rf .git .gitignore
- initiate a new repository:
git init
- add all files (including placeholder content files inside pages/ which later might be changed or remove):
git add -A
Server side:
- create a git bare repository:
- create directory for remote
mkdir mywebsite.git
- go inside that directory
cd mywebsite.git
- create a git bare repository
git --bare init
- create directory for your website (website dir):
mkdir ~/public_html/mywesite.sexy/
Locally:
- edit, add, commit, and push the post-receive-hook script:
- change the
git_work_tree_path
variable to the full path of the website directory in the server. i.egit_work_tree_path=/home/user/public_html/rms.sexy
git add post-receive-hook
git commit -m "post-receive-hook edited to match my website dir"
- add the server-side git bare repository as a git remote:
git remote add remotename ssh://username@server-address:/path/to/mywebsite.git
- push:
git push remotename master
- copy the post-receive-hook to the git bare repository
scp post-receive-hook username@server-address:/path/to/mywebsite.git
Server side: On the git bare repository:
- mv the post-receive-hook to the git bare repository's
hooks/post-receive
file:mv post-receive-hook hooks/post-receive
chmod +x hook/post-receive
- test it by running
./hooks/post-receive
- Files from the git bare repository will be checkout to the
$git_work_tree_path
- Errors due to non-installed python modules will be printed. Take the opportunity to install them. And test again.
- When you manage to run it without errors, the files from the bare repository should be the in website dir (
$git_work_tree_path
), inside the pages directory, including the .html files created by generate_website.py
Locally:
- edit any content .md files
git add -u
git commit -m "changes content"
- push to remote:
git push remotename master
If all goes well the .md your changes will be received by the server, copied to the website dir and converted to html files. Et voila, your website! To see it use the browser and go to the pages/
folder.
Run conversion scripts locally
It is likely that you'd like to see what the website looks like, locally, do so: * run python generate_website.py --local
* browse the .html files inside the pages/
sub-folders
Development & Customization
look and behavior
If you want to change the look and behavior of the website, the director lib/
has the files you need * fonts/
* interaction.js
* jquery-3.1.1.min.js
* style.css
website generator
If you want to change the behavior of the website generator the essential files are: * generate_website.py
: converts .md files onto .html pages, using the templates/template_base.html
. * also contains the template for the menu * templates/template_base.html
the template used by Jinja in generate_website.py
.
Run locally: python generate_website.py --local
Andre Castro 2017
2017 Code Notes