Check-in [315d4d02b5]
Not logged in

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:update README to be m4-bloggery specific
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:315d4d02b5c6a5e9f2aeda4d0100befc4c56b1f8
User & Date: brandon@invergo.net 2013-02-19 17:46:45
Context
2013-02-19
17:47
fix missing paren in new_post template check-in: feb27ee76d user: brandon@invergo.net tags: trunk
17:46
update README to be m4-bloggery specific check-in: 315d4d02b5 user: brandon@invergo.net tags: trunk
17:05
change atom generator check-in: 3e2ea030d3 user: brandon@invergo.net tags: trunk
Changes

Changes to README.md.

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

51
52






53
54
55
56




































# GNU Make and M4 Website Bakery

One of the first hacks that I was really proud of was this website-baking system I built in late 1999 with some venerable old Unix tools, [GNU Make](http://www.gnu.org/software/make/) and [GNU m4](http://www.gnu.org/software/m4/). The article [Using M4 to write HTML](http://web.archive.org/web/19980529230944/http://www.linuxgazette.com/issue22/using_m4.html) by Bob Hepple was my original inspiration, but I think I was able to surpass the utility of the examples given therein.




**You're currently viewing the 'master' branch of this repository.** I've tried to include here many interesting features and ideas for how this technique might be used, including the use of [Pandoc](http://johnmacfarlane.net/pandoc/) for markdown-format source files. I've tried to include a generous amount of internal documentation and comments as well, but it may yet be a lot to absorb at once. To more easily understand what's going on here, be sure to take a look at the 'simple' branch of the repository: http://github.com/datagrok/m4-bakery/tree/simple


## Site Baking





"Website baking" is the pattern of building from templates a mostly- or completely-static website that requires no special software to serve. Baking a website provides huge advantages when it can be employed, because they:


- have fewer vectors for break-ins, 
- easily scale to handle massive amounts of traffic, and 
- may be hosted on commodity hardware or the cheapest of web hosting services.


Of course, with no processing occurring on the server end, it's not possible to host user-interactive features like comments sections, authentication, or e-commerce systems. These days however, many people use third-party tools like [Disqus](http://disqus.com) to implement these features anyway.





In short, if you're not using any of the dynamic features of your web hosting service, you might as well make the whole site static.







## GNU Make and GNU M4




That is of course only an argument for building static websites. Doing it in this _particular_ way may be... ill-advised.


Though m4 may be venerable and may come pre-installed on several modern Unix platforms, it brings along a notoriously cumbersome syntax for defining and calling macros, escaping, quoting, and other things. Sendmail's configuration system serves as a cautionary tale, as it was built upon m4 and is legendary for being obtuse. Employing m4 may be an exercise in masochism.



The difficulty in employing m4 may contribute to my pride in having built a useful tool with it a whole decade+ ago. I hope that this repository will yet serve as an instructive example of how to 'bake' a website using ubiquitous Unix tools, even if every single user ends up swapping out m4 for modern template software, e.g. [Jinja](http://jinja.pocoo.org/).




## Features


- The HTML template is wrapped around .html.m4 files automatically; no boilerplate is necessary in the source file.
- The HTML template is a single file, not a separate header and footer.
- Files named .m4 don't get the template, but still get interpreted by m4.
- Any files not named '.m4' don't get interpreted by m4; they are copied verbatim.
- Macros defined in source .html.m4 files will be expanded in the template. This lets you put complex logic in the template and trigger it from the source file. For example, you could set the page title, toggle a template style, define sidebars, etc.
- Macros defined in the macros file will be expanded in the source files and the template. You can define macros here that you want to be available everywhere.


## Execution




Beginning with source files like this:


	src/
	|-- index.html.m4
	`-- style.css


Along with the Makefile, macros file, and HTML template, running 'make' will
output:


	install -m 644 -D src/style.css dst/style.css
	m4 -P macros.m4 src/index.html.m4 template.html.m4 > src/index.html
	install -m 644 -D src/index.html dst/index.html
	rm src/index.html


And produce the following structure:







	dst/
	|-- index.html
	`-- style.css




































|

|
>
>
>

<
>

<
>
>
>
>

<
>

<
<
<
>

<
>
>
>
>

<
>
>
>
>
>
>

<
>
>
>

<
>

<
>
>

<
>
>
>

<
>

<
<
<
<
<
<
>

<
>
>
>

<
>

<
<
<
>

<
<
>

<
<
<
<
>

<
>
>
>
>
>
>

<
<
<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
51

52
53



54
55


56
57




58
59

60
61
62
63
64
65
66



67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
# m4-bloggery

m4-bloggery is a simple static site generator that depends only on m4,
Make and a Markdown parser.  It is based on m4-bakery[1] by Datagrok.
m4-bloggery adds some extra features for a blog-oriented site, namely
a blog/news index and an Atom XML feed. 


# Requirements


* Make (probably only the GNU variant; I haven't checked if it depends
  on any GNU extensions)
* M4 (any version will probably work)
* Any command-line program to convert Markdown into HTML (optional)


# Usage




## Creating pages


Some example files are provided in the tree.  It is easiest to work
with Markdown files, so I'll only talk about that here.  To create a
new page, simply create a file under the `src/` directory with the
`.md.m4` extension. Inside, you can define several macros:


* TITLE: the title of the page
* DATE: the date the page was created
* UPDATE: the date that a page was updated
* TAGS: a space-separated list of tags for the page (note: I have not
        implemented a proper tagging system)
* BODY: the main text of the page


You define a macro by putting some text in between a nested pair of
parentheses and braces, with the text surrounded by quotes.  So, to
define the title of the page, you would add:


    TITLE({"This is my site"})


The exception is the BODY macro, which requires an extra nested pair
of braces and quotes:


    BODY({"{"
        This is the main text of this page, which is boring.
    "}"})


Why do you have to do that?  Eh...the vagaries of quoting in m4. 







## Creating blog/news posts


There is a shortcut to creating a new post: the "new-post" Make
target.  You must supply a value to the TITLE variable on the
command-line when you use this target:


    $ make new-post TITLE="How amazingly simple"




## Generating the site



Once you have created all of your pages, simply make the `all` target:





    $ make all


This will first run the pages through Markdown to generate the HTML
and then it runs them through m4 to construct full pages out of the
layouts.  The generated site will be moved into a directory called
`dst`.  Whatever directory structure you have under `src` will be
simply mirrored to `dst`.  In the end, the contents of `dst` are to be
served.




## Deployment

You can automatically deploy the website to your server via rsync
using the `deploy` make target:

    $ make deploy

You should modify the file `auth.mk` to include your username
(user@server) and the document root where things will be uploaded:

    SSH_USER = me@myserver.com
    DOC_ROOT = ~/public_html

# Customization

You can customize this to your heart's desire.  I hate web design so
the default design is rather minimalist.  Modify the files in the
`templates` directory to change the site structure (particularly
`main.html.m4`).  Notice all of those `m4_divert()` calls?  m4 uses
those to determine where and how to merge the various templates.  You
shouldn't need to change those.

You can modify the css under the `src/css` sub-directory.

# Example Sites

http://brandon.invergo.net

# Contact

Brandon Invergo <brandon [at] invergo [dot] net

# Footnotes

[1]  https://github.com/datagrok/m4-bakery