Wallogit.com
2017 © Pedro Peláez
A static website builder. Create markdown files and a theme and then serve up as HTML.
Greengrape provides a simplified way to create a website without complex configurations. You simply create content in Markdown files in a structured set of folders and let the site produce the navigation and layout., (*1)
A couple advantages with this approach as compared to traditional CMS packages are as follows:, (*2)
Greengrape is written for PHP 5.3., (*3)
You can download Greengrape from Github at https://github.com/sumpygump/greengrape/, (*4)
If you download as an archive, you can start making changes and commit into your own version control., (*5)
$ wget https://github.com/sumpygump/greengrape/archive/master.tar.gz $ tar xzf master.tar.gz
This will create a directory called greengrape-master, (*6)
You can also clone the repository like so:, (*7)
$ git clone git://github.com/sumpygump/greengrape.git
Once you have the files on your computer, you need to complete a few steps to get the site running., (*8)
Greengrape uses a few third-party libraries. You must use composer to fetch the needed libraries., (*9)
If you haven't installed composer yet, you can download the composer.phar executable or use the installer:, (*10)
$ curl -s https://getcomposer.org/installer | php
Now you can complete the setup by running the following, (*11)
Install dependencies with composer, (*12)
$ composer.phar install
This will use the composer.json file to install the Twig and Markdown
libraries., (*13)
Copy config.ini-dist to config.ini, (*14)
$ cp config.ini-dist config.ini
Copy .htaccess-dist to .htaccess and edit RewriteBase, (*15)
$ cp .htaccess-dist .htaccess $ vi .htaccess
You need to edit line 8 in that file. Change it to include the Base URL of
where you have placed the files. For example, if you put the
greengrape-master directory in /var/www/testing/greengrape-master folder in you apache
webroot, (and assuming /var/www is the webroot) you will need to edit the line to read:, (*16)
RewriteBase /testing/greengrape-master/
If you installed this on a server where the greengrape directory is at the root, then it should read, (*17)
RewriteBase /
Make the cache directory world writable, (*18)
$ chmod a+w cache -R
You could also update this directory to be owned by your apache user (like www-data), but I'll let you decide., (*19)
Load the site up in your browser and you should see the welcome page., (*20)
All of your content resides in the content folder. By default you can see
there is an index.md file there. That file contains the Markdown for the the
home page., (*21)
You can add more .md (Markdown) files in this directory and they will be available in your
browser at a URL sans the .md extension. For example, if I created a file
called hello.md it would be available at mysite.com/hello., (*22)
You can add folders in the content folder and these will be treated as top
level navigation. I could add a new projects directory and some files in that
folder, like so:, (*23)
content
├── index.md
└── projects
├── funstuff.md
└── index.md
The contents of projects/index.md would be served up if I accessed the URL
mysite.com/projects/ and the funstuff.md file would be available at
mysite.com/projects/funstuff, (*24)
Now when I refresh the home page, I see a top level navigation at the top
showing Home and Projects. Greengrape automatically adds this in based on
the folders in the root of the content folder. It will also generate a
sub-navigation at the second level from the root of content. It only
generates navigation automatically as far as that second level, but you can
make folders as deeply nested as you like., (*25)
The items appear in the navigation according to alphabetical order. You can
alter the order by prepending the folder names with a number and a dot, (e.g.
01.projects), the 01. will be stripped and so the URLs will display as
mysite.com/projects., (*26)
If you don't want a folder to appear in the navigation list, prepend the folder
name with an underscore (_)., (*27)
You can add all kinds of content using the easily readable Markdown syntax by just editing folders and files on your computer with the text editor of your choice. That is the beauty of Greengrape., (*28)
For a complete reference of the syntax of Markdown please see the Markdown documentation., (*29)
To add images to your Markdown files, you can add them to the assets
directory; assets/img is a good place for images. In your Markdown files you
can reference them using the following examples:, (*30)
See this image: .
or, (*31)
See this image: ![alt text][id] ... [id]: assets/img/coolimage.png "Optional title attribute"
You can also reference images from another domain too, just include http://.
For more information about Markdown syntax for images, see the documentation
for images in Markdown., (*32)
Greengrape will automatically put the correct BaseUrl on the path to the image, so if the install location of the site changes, your references will stay in tact., (*33)
Links work the same way in Greengrape as with images. It will include the
BaseUrl of wherever Greengrape is installed to ensure the links stay correct if
the install directory ever changed. Just make the reference as if at the root
of the greengrape folder like so (this is using our earlier example of the
project/funstuff.md path):, (*34)
Check out the [fun stuff](projects/funstuff) I did.
You can of course add links to other domains as well. Don't forget to include
the http://:, (*35)
Link to [google](http://google.com/).
The themes folder is where the layout and styles and javascript reside for
your site. Currently, the only theme is the default theme called, "fulcrum."
Greengrape is setup in a way that you could create a new theme and even switch
themes while not disturbing your content, which lives separately in the
content folder., (*36)
There is no advanced documentation on making a theme, but to begin, I would suggest making a copy of the fulcrum theme and editing the files., (*37)
The theme files use Twig as the templating engine., (*38)
The key files of a theme are the following:, (*39)
layout.html - This is the basic layout of the theme and all pages will use
this as the boilerplate for serving the base HTML tags., (*40)
templates/default.html - The templates folder contains snippets of HTML that
can be used by content block. Currently it is not possible to assign
different templates to content files (the .md files) but it will be a
future enhancement to assign a content file to use a specific template file.
Currently all content files use the default template., (*41)
templates/error.html, templates/404.html, templates/_navigation.html,
templates/_subnavigation.html - These files are all used internally by
Greengrape to serve error messages, 404 pages and the navigation. Since it
is HTML with Twig templating, it is useful to know you can make
modifications to the output to modify a theme., (*42)
css, img, js - These folders contain CSS, images and JavaScript files.
These files can be referenced in the layout.html and templates using the
following Twig syntax:, (*43)
<link rel="stylesheet" href="{{ asset.file('css/bootstrap.min.css') }}" />
<img class="pull-left" src="{{ asset.file('img/greengrape.jpg') }}"
<script type="text/javascript" src="{{ asset.file('js/plugins') }}"></script>
Note that if you leave the extension of the filename, Greengrape will
automatically append a .js or .css depending on the folder being
referenced., (*44)
You can also add other assets to a theme and reference them in the same way,
using the asset.file() syntax., (*45)
The config file is a simple .ini file to provide some settings to Greengrape.
The example file is similar to the following:, (*46)
; Site name sitename = "My awesome site" ; Theme to use theme = "fulcrum" ; Whether cache is enabled enable_cache = false ; Additional view params author = "Doc Brown" description = "A sample website built with Greengrape"
The most important things about this file are the sitename, theme and
enable_cache settings., (*47)
sitename provides the default title for the sitetheme tells Greengrape with theme to use in the themes folderenable_cache will enable or disable the cacheYou can add other param here and they will be passed into the layout file of
the theme using Twig's {{ }} syntax, for example:, (*48)
<meta name="author" content="{{ layout.author }}">
Additional params would be useful for include Google Analytics account numbers that need to be output with the HTML layout, for example., (*49)
Greengrape's cache will serve up a cached file that represents any content file that is accessible if the corresponding file exists in the cache, otherwise it will generate the HTML output and save it to the cache., (*50)
There is not a robust way to clear the cache in this version, but it is
possible to clear the cache by deleting the files in the cache/content
folder. A more advanced cache clearing system will be developed in future
versions., (*51)
It is also possible to clear the cache by appending the query string parameter
?cache=clear to a request. This will clear the cache for the given requested
page., (*52)
It is suggested for ease of development to adjust the setting in the config.ini file to disable the cache while the site's content is under development and then enabling it when it is relatively stable., (*53)
A static website builder. Create markdown files and a theme and then serve up as HTML.
MIT
A static website builder. Create markdown files and a theme and then serve up as HTML.
MIT