search

cidrblock / drawthe.net

drawthe.net draws network diagrams dynamically from a text file describing the placement, layout and icons. Given a yaml file describing the hierarchy of the network and it's connections, a resulting diagram will be created.
http://go.drawthe.net
1.11k stars 130 forks source link
diagram icons network

readme

drawthe.net: Decent looking diagrams for engineers.

drawthe.net draws network diagrams dynamically from a text file describing the placement, layout and icons. Given a yaml file describing the hierarchy of the network and it's connections, a resulting diagram will be created.

screenshot

Motivation

Complex network diagrams typically involve specific place of icons, connections and labels using a tool like Visio or OmniGraffle using a mouse and constantly zooming in and out for single pixel placement. The goal behind drawthe.net, was to be able to describe the digram in a text file and have it rendered in SVG in the browser.

I simply wanted to be able to draw network diagrams as fast as it could be done on a dry-erase board without using a mouse.

Quick start

http://go.drawthe.net

Clear the editor and paste the following in, then click draw or ctrl-enter.

diagram:
  fill: "white"
  rows: 5
  columns: 5
title:
  author: Your Name
  company: Comapny Name
  color: black
  logoFill: white
  logoUrl: https://upload.wikimedia.org/wikipedia/commons/b/b3/Wikipedia-logo-v2-en.svg
  text: Hello world
  subText: additional information about this diagram
  type: bar
  stroke: black
# Set defaults for icons, groups, connections
iconDefaults: &iconDefaults
  color: black
  fill: white
  stroke: black
  iconFamily: aws
groupDefaults: &groupDefaults
  fill: "none"
  color: black
  stroke: black
connectionDefaults: &connectionDefaults
  color: "black"
  stroke: "black"
noteDefaults: &noteDefaults
  color: black
  fill: white
  stroke: black
  xAlign: center
  yAlign: center
# Add the icons
icons:
  dns: {<<: *iconDefaults, icon: net_route53_hostedzone, x: 2, y: 3 }
  lb: {<<: *iconDefaults, icon: cmpt_elasticloadbalancing, y: "-1" }
  server1: {<<: *iconDefaults, icon: cmpt_ec2_instance, x: "-1", y: "-1" }
  server2: {<<: *iconDefaults, icon: cmpt_ec2_instance, x: "+1" }
  server3: {<<: *iconDefaults, icon: cmpt_ec2_instance, x: "+1" }
# Add the gorups
groups:
  servers: { <<: *groupDefaults, name: Web Servers, members: [server1, server2, server3] }
# Add conneections
connections:
  - { <<: *connectionDefaults, endpoints: [dns, lb] }
  - { <<: *connectionDefaults, endpoints: [lb, servers] }
notes:
  note1:
    <<: *noteDefaults
    x: 0
    y: 3
    text: "##Note\n\nThis is the text for the note."

Hopefully, the following diagram is created.

screenshot

Overview

The YAML document has major sections which describe the diagram. These are the basic root types:

diagram: The page on which the diagram will be drawn.
title: Information about the diagram.
icons: Objects to be placed on the diagram.
notes: Text boxes with information.
connections: Lines drawn between objects.
groups: Collections of objects.

Custom sections

The YAML document above has the following additional custom sections:

iconDefaults: A YAML anchor which describes common icon attributes which will be inherited later.
groupDefaults: A YAML anchor which describes common group attributes which will be inherited later.
connectionDefaults: A YAML anchor which describes common connection attributes which will be inherited later.
noteDefaults: A YAML anchor which describes common note attributes which will be inherited later.

YAML reference: https://en.wikipedia.org/wiki/YAML

Placement

Icons and notes have the following attributes, which allows the object to be placed and sized on the place.

x: The X coordinate value.
y: The Y coordinate value.
w: The width of the object, in X coordinate steps, extending right toward the right side of the screen.
h: The height of the object, in Y coordinate steps, extending down toward the bottom of the diagram.

Basic styling

Common to most entities are the following:

color: The color of the text.
fill: Sets the color inside the object.
stroke: Sets the color of the line drawn around the object.

Icons

The following icon families are available:

Icons have the following basic attributes:

iconFamily: The family from which to pull the icon.
icon: The name of the icon within the family.
iconFill: Set the color inside the icon.
iconStroke: Sets the color of the line drawn within the icon.

Each icon and icon family may behave differently when the fill and stroke are applied, review the icon cut sheets to see the icons available for each family with the iconFill and iconStroke set.

Notes

Notes can be plain text or markdown. See the 'notes' example for the use of markdown. (Indentation is critical when using markdown for notes.)

Additional examples

http://go.drawthe.net

Click on the examples menu for a sample of different diagram layouts and styles.

Troubleshooting

The most common mistake I've made is in the YAML syntax. The developer tools window in chrome should give you an idea of what might be wrong.

It's also handy to comment out lines (with a #) to see where the issue may be.

API Reference

Diagram

diagram:

Title

title:

Icons

The icon's key will be used as the text value, therefore icon names have to be unique.

icons:

Groups

Groups are drawn in order, so place groups that should have a lower z-index at the top of the group array. A group is the smallest rectangle that includes it's members, so in the case of large groups, it will only be necessary to include the upper-left and lower-right most members.

groups:

Connections

Connections are an array of individual connections. The order is insignificant because connections will always be drawn from left to right.

connections:

Curve definitions are directly from d3.js: https://github.com/d3/d3-shape (only a subset are implemented.)

Notes

See the example call 'Notes' for examples of these attributes.

notes:

Each note is an html flexbox. For a good explanation of flex-boxes: https://css-tricks.com/snippets/css/a-guide-to-flexbox/
Notes can also contain markdown converted by: Showdown.js https://github.com/showdownjs/showdown/wiki/Showdown's-Markdown-syntax

Built with great open source software

Contributing

Please do.

Versioning

1.0 Initial release.

Authors

License

This project is licensed under the MIT License. MIT License.

Additional development information

Converting icons

  1. copy the icons into a images/xxxx directory
  2. clean up the names a little
  3. convert from svg to eps and back to svg (this sizes the svg to the bounding window of the icon)
  4. use svgo to cleaup the svg files

azure-cloud

cd build/images/azureCloud
cp ~/Downloads/Microsoft_CloudnEnterprise_Symbols_v2.5_PUBLIC/Symbols/CnE_Cloud/SVG/*.svg .
rename 's/[^a-zA-Z0-9_.]//g' *.svg
rename -f 'y/A-Z/a-z/' *.svg
rename 's/^Azure//g' *.svg
for i in `pwd`/*.svg; do inkscape $i -E ${i%.svg}.eps; done
rm *.svg
for i in `pwd`/*.eps; do inkscape $i -l ${i%.eps}.svg; done
rm *.eps
svgo .
cd .. && node ./build_list.js

AWS

mkdir aws && cd aws
find ~/Downloads/AWS_Simple_Icons_EPS-SVG_v16.2.22/ -type f -name \*.eps -exec cp \{\} . \;
for i in `pwd`/*.eps; do inkscape $i -l ${i%.eps}.svg; done
rm *.eps

rename 's/Amazon//g' *.svg
rename 's/AWS//g' *.svg
rename 's/^Analytics/anlt/g' *.svg
rename 's/^Application-Services/app/g' *.svg
rename 's/^Compute/cmpt/g' *.svg
rename 's/^Database/db/g' *.svg
rename 's/^Developer/dev/g' *.svg
rename 's/^Enterprise/ent/g' *.svg
rename 's/^General/gen/g' *.svg
rename 's/^Internet-Of-Things_IoT/iot_/g' *.svg
rename 's/^Management-Tools/mgmt/g' *.svg
rename 's/^Mobile-Services/mbl/g' *.svg
rename 's/^Networking/net/g' *.svg
rename 's/^On-Demand-Workforce_MechanicalTurk/odwmt/g' *.svg
rename 's/^Security-Identity/sec/g' *.svg
rename 's/^Storage-Content-Delivery/stor/g' *.svg
rename 's/[^a-zA-Z0-9_.]//g' *.svg
rename -f 'y/A-Z/a-z/' *.svg
svgo .