Installing blockdiag on OS X is fairly straight forward. A couple pip commands later and you’ll be done.

Note: If you are running python in a virtualenv, don’t forget to activate it before installing your pip modules or they’ll be installed globally (my shell prompt changes to include a (pelican) in it when I’m inside the virtualenv.

Installing blockdiag modules

(pelican)[louisk@iPwn cryptomonkeys.com ]$ pip install blockdiag nwdiag blockdiagcontrib-eps blockdiagcontrib-excelhogan blockdiagcontrib-cisco seqdiag blockdiagcontrib-square blockdiagcontrib-tex blockdiagcontrib-labeledbox blockdiagcontrib-class blockdiagcontrib-excelshape blockdiagcontrib-math
Collecting blockdiag
  Downloading blockdiag-1.5.3-py2.py3-none-any.whl (2.7MB)
    100% |████████████████████████████████| 2.7MB 45kB/s
Collecting nwdiag
  Downloading nwdiag-1.0.4-py2.py3-none-any.whl (7.7MB)
    100% |████████████████████████████████| 7.7MB 26kB/s
Collecting blockdiagcontrib-eps
  Downloading blockdiagcontrib_eps-0.1.1-py2.py3-none-any.whl
Collecting blockdiagcontrib-excelhogan
  Downloading blockdiagcontrib-excelhogan-0.1.0.tar.gz
Collecting blockdiagcontrib-cisco
  Downloading blockdiagcontrib-cisco-0.1.8.tar.gz (5.8MB)
    100% |████████████████████████████████| 5.8MB 21kB/s
Collecting seqdiag
  Downloading seqdiag-0.9.5-py2.py3-none-any.whl (2.6MB)
    100% |████████████████████████████████| 2.6MB 39kB/s
Collecting blockdiagcontrib-square
  Downloading blockdiagcontrib-square-0.1.3.tar.gz
Collecting blockdiagcontrib-tex
  Downloading blockdiagcontrib-tex-0.2.2.tar.gz
Collecting blockdiagcontrib-labeledbox
  Downloading blockdiagcontrib-labeledbox-0.1.1.tar.gz
Collecting blockdiagcontrib-class
  Downloading blockdiagcontrib-class-0.1.3.tar.gz
Collecting blockdiagcontrib-excelshape
  Downloading blockdiagcontrib-excelshape-0.1.0.zip
Collecting blockdiagcontrib-math
  Downloading blockdiagcontrib_math-0.9.0-py2.py3-none-any.whl
Collecting webcolors (from blockdiag)
  Downloading webcolors-1.5.tar.gz
Requirement already satisfied (use --upgrade to upgrade): setuptools in /Users/louisk/ownCloud/documents/Work/Cryptomonkeys/pelican/lib/python3.4/site-packages (from blockdiag)
Collecting funcparserlib (from blockdiag)
  Downloading funcparserlib-0.3.6.tar.gz
Requirement already satisfied (use --upgrade to upgrade): Pillow in /Users/louisk/ownCloud/documents/Work/Cryptomonkeys/pelican/lib/python3.4/site-packages (from blockdiag)
Collecting openpyxl (from blockdiagcontrib-excelhogan)
  Downloading openpyxl-2.2.5.tar.gz (108kB)
    100% |████████████████████████████████| 110kB 65kB/s
Collecting jdcal (from openpyxl->blockdiagcontrib-excelhogan)
  Downloading jdcal-1.0.tar.gz
Building wheels for collected packages: blockdiagcontrib-excelhogan, blockdiagcontrib-cisco, blockdiagcontrib-square, blockdiagcontrib-tex, blockdiagcontrib-labeledbox, blockdiagcontrib-class, blockdiagcontrib-excelshape, webcolors, funcparserlib, openpyxl, jdcal
  Running setup.py bdist_wheel for blockdiagcontrib-excelhogan
  Stored in directory: /Users/louisk/Library/Caches/pip/wheels/15/8b/27/9e1f5a5d71d160e3e461cf1199cfdc080c6ebe83c60654beaa
  Running setup.py bdist_wheel for blockdiagcontrib-cisco
  Stored in directory: /Users/louisk/Library/Caches/pip/wheels/db/d6/f2/ebc6ca11fca82898b1d80761b288329e876eab32f34bcd6d12
  Running setup.py bdist_wheel for blockdiagcontrib-square
  Stored in directory: /Users/louisk/Library/Caches/pip/wheels/1f/07/ea/794a37b8275359269d4ae8e69107e1d6e7c166a3dcd567c635
  Running setup.py bdist_wheel for blockdiagcontrib-tex
  Stored in directory: /Users/louisk/Library/Caches/pip/wheels/88/ad/cb/8f9603c32ecdee6a8235a1f8e8e9c8ca0c9cefc68290e2fb8d
  Running setup.py bdist_wheel for blockdiagcontrib-labeledbox
  Stored in directory: /Users/louisk/Library/Caches/pip/wheels/95/1d/6d/0a7c4bcc134b70e43709c6af6b022d807d311686709f756a7a
  Running setup.py bdist_wheel for blockdiagcontrib-class
  Stored in directory: /Users/louisk/Library/Caches/pip/wheels/71/7c/3e/b1d791f52c4fd973b6a9549c5cb7c2eea5fb7399597f87b767
  Running setup.py bdist_wheel for blockdiagcontrib-excelshape
  Stored in directory: /Users/louisk/Library/Caches/pip/wheels/1d/9b/54/d8f1979266dc30c10e36f833f26fc31daf6905a90e1ea815fa
  Running setup.py bdist_wheel for webcolors
  Stored in directory: /Users/louisk/Library/Caches/pip/wheels/0a/9b/89/83fb075ab22d93e6525de4a6b29fa42e2a49f070a19e0dcd3a
  Running setup.py bdist_wheel for funcparserlib
  Stored in directory: /Users/louisk/Library/Caches/pip/wheels/1d/4f/13/694848fa3a4ca3d7080c606603dc8f92d26d55c8c0abb1fe9d
  Running setup.py bdist_wheel for openpyxl
  Stored in directory: /Users/louisk/Library/Caches/pip/wheels/ff/19/0c/642824e09ffb56bea48aa77b6f00f220a3b42125124eb4f726
  Running setup.py bdist_wheel for jdcal
  Stored in directory: /Users/louisk/Library/Caches/pip/wheels/91/14/40/9578071e3df07cbbbdce9002ca8c5de065c74c4f840c264d86
Successfully built blockdiagcontrib-excelhogan blockdiagcontrib-cisco blockdiagcontrib-square blockdiagcontrib-tex blockdiagcontrib-labeledbox blockdiagcontrib-class blockdiagcontrib-excelshape webcolors funcparserlib openpyxl jdcal
Installing collected packages: webcolors, funcparserlib, blockdiag, nwdiag, blockdiagcontrib-eps, jdcal, openpyxl, blockdiagcontrib-excelhogan, blockdiagcontrib-cisco, seqdiag, blockdiagcontrib-square, blockdiagcontrib-tex, blockdiagcontrib-labeledbox, blockdiagcontrib-class, blockdiagcontrib-excelshape, blockdiagcontrib-math
Successfully installed blockdiag-1.5.3 blockdiagcontrib-cisco-0.1.8 blockdiagcontrib-class-0.1.3 blockdiagcontrib-eps-0.1.1 blockdiagcontrib-excelhogan-0.1.0 blockdiagcontrib-excelshape-0.1.0 blockdiagcontrib-labeledbox-0.1.1 blockdiagcontrib-math-0.9.0 blockdiagcontrib-square-0.1.3 blockdiagcontrib-tex-0.2.2 funcparserlib-0.3.6 jdcal-1.0 nwdiag-1.0.4 openpyxl-2.2.5 seqdiag-0.9.5 webcolors-1.5
(pelican)[louisk@iPwn cryptomonkeys.com ]$

Testing out blockdiag

Here are the edits for your pelicanconf.py:

PLUGINS = [ ... 'liquid_tags.graphviz', 'liquid_tags.b64img', 'liquid_tags.diag' ]

Both the graphviz and diag sub modules of Liquid_Tags produce base64 images inline, which is why we need to also include the b64img sub module.

Now that we have things setup, we should be able to insert code like this into our markdown documents and have it rendered into an image on the fly.

Graphviz

{% graphviz 
	dot {
		digraph G {
			main -> parse -> execute;
			main -> init;
			main -> cleanup;
			execute -> make_string;
			execute -> printf
			init -> make_string;
			main -> printf;
			execute -> compare;
		}
    }
%}

If everything is working properly, this should render as the following graphic:

{% graphviz dot { digraph G { main -> parse -> execute; main -> init; main -> cleanup; execute -> make_string; execute -> printf init -> make_string; main -> printf; execute -> compare; } } %}

Graphviz documentation is available here

Blockdiag

Moving on to Blockdiag. Lets start with a simple example:

{% blockdiag
	blockdiag {
   	    A -> B -> C;
   	    B -> D;
   	}
%}

If everything works properly, we should end up with a graphic here:

{% blockdiag blockdiag { A -> B -> C; B -> D; } %}

We’ve intentionally started out very simple. It can get complicated quickly. Blockdiag documentation is available here. Blockdiag also offers other kinds of diagrams including Sequence Diagrams, Network Diagrams, and even Packet Diagrams. I’ll show some simple examples of each.

Sequence diagram

{% blockdiag
	seqdiag {
		A -> B -> C;
		B -> D;
	}
%}

{% blockdiag seqdiag { A -> B -> C; B -> D; } %}

Network Diagram

{% blockdiag
	nwdiag {
		network dmz {
			web01;
			web02;
			stg01;
		}

		network internal {
			web01;
			web02;
			db01;
			db02;
		}
	}
%}

{% blockdiag nwdiag { network dmz { web01; web02; stg01; }

    network internal {
        web01;
        web02;
        db01;
        db02;
    }
}

%}

Packet Diagram

{% blockdiag
	packetdiag {
		0-7: Source Port
		8-15: Destination Port
		16-31: Sequence Number
		32-47: Acknowledgment Number
	}
%}

{% blockdiag packetdiag { 0-7: Source Port 8-15: Destination Port 16-31: Sequence Number 32-47: Acknowledgment Number } %}

Rack Diagram

{% blockdiag
    rackdiag {
      24U;

      1: UPS [3U, 0.5A, 10kg];
      5: Disk Array [2U, 0.5A];
      7: DB Master
      8: DB Mirror (1)
      9: DB Mirror (2)
      11: Web Server (1)
      11: Web Server (2)
      12: Web Server (3)
      12: Web Server (4)
      14: LoadBalancer
    }
%}

{% blockdiag rackdiag { 24U;

  1: UPS [3U, 0.5A, 10kg];
  5: Disk Array [2U, 0.5A];
  7: DB Master
  8: DB Mirror (1)
  9: DB Mirror (2)
  11: Web Server (1)
  11: Web Server (2)
  12: Web Server (3)
  12: Web Server (4)
  14: LoadBalancer
}

%}

Summary

From here, you can diagram most anything you need. The best part, you can version all of this since its plain text. Now its easy to keep diagrams current, reflecting reality, and you can even automate the creation of diagrams, since they’re just text.