{"id":13551047,"url":"https://github.com/asciitosvg/asciitosvg","last_synced_at":"2025-04-03T01:31:05.055Z","repository":{"id":34625219,"uuid":"38574718","full_name":"asciitosvg/asciitosvg","owner":"asciitosvg","description":"Create beautiful SVG renderings of ASCII diagrams.","archived":false,"fork":false,"pushed_at":"2022-11-26T18:04:16.000Z","size":149,"stargazers_count":212,"open_issues_count":9,"forks_count":16,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-11-03T21:34:00.806Z","etag":null,"topics":["ascii-art","asciitosvg","beautiful-svg-diagrams","diagrams","markdown-extension","svg"],"latest_commit_sha":null,"homepage":"https://github.com/asciitosvg/asciitosvg","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asciitosvg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-07-05T15:56:04.000Z","updated_at":"2024-09-07T08:15:50.000Z","dependencies_parsed_at":"2023-01-15T08:08:57.794Z","dependency_job_id":null,"html_url":"https://github.com/asciitosvg/asciitosvg","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asciitosvg%2Fasciitosvg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asciitosvg%2Fasciitosvg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asciitosvg%2Fasciitosvg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asciitosvg%2Fasciitosvg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asciitosvg","download_url":"https://codeload.github.com/asciitosvg/asciitosvg/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246922025,"owners_count":20855341,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ascii-art","asciitosvg","beautiful-svg-diagrams","diagrams","markdown-extension","svg"],"created_at":"2024-08-01T12:01:41.628Z","updated_at":"2025-04-03T01:31:02.082Z","avatar_url":"https://github.com/asciitosvg.png","language":"Go","funding_links":[],"categories":["Go","others"],"sub_categories":[],"readme":"# ASCIIToSVG\n\n    .-------------------------.\n    |                         |\n    | .---.-. .-----. .-----. |\n    | | .-. | +--\u003e  | |  \u003c--| |\n    | | '-' | |  \u003c--| +--\u003e  | |\n    | '---'-' '-----' '-----' |\n    |  ascii     2      svg   |\n    |                         |\n    '-------------------------'\n\n   https://github.com/asciitosvg\n\nCreate beautiful SVG diagrams from ASCII art.\n\n## Introduction\n\n### License\n\nASCIIToSVG is copyright © 2012-2018 The ASCIIToSVG contributors, and is\ndistributed under an MIT license. All code without explicit copyright retains\nthis license. Any code not adhering to this license is explicit in its own\ncopyright.\n\n### What does it do?\n\nASCIIToSVG is a pretty simple Go library (with an accompanying CLI tool) that\nparses ASCII art diagrams, attempting to convert them to an aesthetically\npleasing SVG output. Someone snidely remarked in a HN thread that if you make\na thing that generates visual output, show some examples of that output. Ask\nGitHub to support insertion of SVG into their Markdown. In the meantime, you\ncan easily get example output by running `a2s -L`.\n\n### What about that other project?\n\nThe original code at https://github.com/dhobsd/asciitosvg suffers from a\nnumber of issues. It isn't particularly efficient in what's effectively a graph\nsearch problem, and its implementation in PHP leaves a bit to be desired. Some\nside-effects of this are that things one would really expect (like using `+`\nfor angled polygon corners) are not supported. This project subsumes the other,\nwhich will eventually become unmaintained. Another advantage to the Go version\nis that it supports UTF-8 inputs natively. Other features, like tab expansion,\nhave also been introduced.\n\nSome other features, like custom objects, have not yet been implemented.\n\n### So... why did you do this?\n\nThere are a few reasons:\n\n * We feel that Markdown is a great format for authoring documents.\n * When authoring technical documents, it's common to want to embed diagrams.\n * People say pictures are worth a thousand words.\n\nMarkdown support for inline images isn't particularly great, because you\ncannot view the image in text mode. An ASCII diagram is usually doable for\nmany illustrations, but is often rendered as text in the HTML output. We'd\nlike the best of both worlds.\n\n### Aren't there already things that do this?\n\nWell, yes. There is a project called [ditaa][1] that has some of this\nfunctionality. When dhobsd initially implemented A2S, ditaa left a couple key\npoints to be desired:\n\n * Its annotation format was too verbose, distracting from the visual content\n in text mode.\n * Its output was a rasterized format, so it didn't scale well.\n\nLater, ditaa became unusable. The [software it was integrated with][2] was\nwritten in PHP, and had to shell out to run ditaa. Because ditaa was written in\nJava, new JVMs were spawned often to provide real-time feedback on diagram\nchanges. The functionality was re-implemented in PHP to output SVG, but this\nultimately ran into the issues described above. Hence this project.\n\n## Compilation and Usage\n\nTo get the CLI tool, make sure `$GOPATH/bin` is in your `$PATH`. Run:\n\n    $ go get github.com/asciitosvg/asciitosvg/cmd/a2s\n    $ a2s -h\n     .-------------------------.\n     |                         |\n     | .---.-. .-----. .-----. |\n     | | .-. | +--\u003e  | |  \u003c--| |\n     | | '-' | |  \u003c--| +--\u003e  | |\n     | '---'-' '-----' '-----' |\n     |  ascii     2      svg   |\n     |                         |\n     '-------------------------'\n\n    https://github.com/asciitosvg\n\n    [1,0]: {\"fill\":\"#88d\",\"a2s:delref\":1}\n\n    Usage of go/bin/a2s:\n      -L\tGenerate SVG of the a2s logo.\n      -b\tDisable drop-shadow blur.\n      -f string\n            Font family to use. (default \"Consolas,Monaco,Anonymous Pro,Anonymous,Bitstream Sans Mono,monospace\")\n      -i string\n            Path to input text file. If set to \"-\" (hyphen), stdin is used. (default \"-\")\n      -o string\n            Path to output SVG file. If set to \"-\" (hyphen), stdout is used. (default \"-\")\n      -t int\n            Tab width. (default 8)\n      -x int\n            X grid scale in pixels. (default 9)\n      -y int\n            Y grid scale in pixels. (default 16)\n\n\nTo play with the library:\n\n    $ go get github.com/asciitosvg/asciitosvg\n\nDocumentation on the API is available through your local `godoc` server.\n\n## Drawing diagrams\n\nEnough yammering about the impetus, code, and functionality. I bet you want\nto draw something. ASCIIToSVG supports a few different ways to do that. \n\n### Basics: polygons and line segments\n\nASCIIToSVG supports concave and convex polygons with rounded or\ndegree-appropriate corners. Horizontal, vertical, and diagonal lines are all\nsupported. ASCIIToSVG has nearly complete support for output from\n[App::Asciiio][3]. Edges of polygons and line segments can be drawn using the\nfollowing characters:\n\n * `-` or `=`: Horizontal lines, solid or dashed (respectively).\n * `|` or `:`: Vertical lines, solid or dashed (respectively).\n * `\\` or `/`: Diagonal lines.\n * `+`: Edge of a line segment, or an angled corner.\n\nTicks and dots can be added into the middle of a line segment using `x` and\n`o`, respectively. Note that these characters cannot be inserted into diagonal\nlines, and they cannot begin a line.\n\nTo draw a polygon or turn a line, corners are necessary. The following\ncharacters are valid corner characters:\n\n * `'` and `.`: Quadratic Bézier corners\n * `+`: Angled corners.\n\nThe `+` token is a control point for lines. It denotes an area where a line\nintersects another line or traverses a box boundary.\n\nA simple box with 3 rounded corners and a line pointing at it:\n\n    +----------.\n    |          | \u003c---------\n    '----------'\n\nDiagonals may be used to form a closed polygon, but this is rarely a good idea.\n\n### Basics: markers\n\nMarkers can be attached at the end of a line to give it a nice arrow by\nusing one of the following characters:\n\n * `\u003c`: Left marker\n * `\u003e`: Right marker\n * `^`: Up marker\n * `v`: Down marker\n\n### Basics: text\n\nText can be inserted at almost any point in the image. Text is rendered in\na monospaced font. There aren't many restrictions, but obviously anything\nyou type that looks like it's actually a line or a box is going to be a good\ncandidate for turning into some pretty SVG path. Here is a box with some\nplain black text in it:\n\n    .-------------------------------------.\n    | Hello here and there and everywhere |\n    '-------------------------------------'\n\n### Basics: formatting\n\nIt's possible to change the format of any boxes / polygons you create. This\nis done (true to markdown form) by providing a reference on the top left\nedge of the object, and defining that reference at the bottom of the input.\nReferences *must* appear in the input *below* the objects they are associated\nwith, and preferably at the bottom of the diagram.\n\nAn example:\n\n    .-------------.  .--------------.\n    |[Red Box]    |  |[Blue Box]    |\n    '-------------'  '--------------'\n\n    [Red Box]: {\"fill\":\"#aa4444\"}\n    [Blue Box]: {\"fill\":\"#ccccff\"}\n\nText appearing within a stylized box automatically tries to fix the color\ncontrast if the black text would be too dark on the background. The\nreference commands can take any valid SVG properties / settings for a\n[path element][4]. The commands are specified in JSON form, one per line.\nReference commands do not accept nested JSON objects -- don't try to\nplace additional curly braces inside! (Indeed, the current Go implementation\ncurrently requires all JSON values other than `a2s:delref` to be strings.)\n\nBy default, the text of a reference is rendered inside the polygon, and the\nreference is left in-tact in the output. You can remove the reference text\nusing the `a2s:delref` option; if it is set to any valid JSON value, it will\nremove the reference text. You can use the `a2s:label` to replace the text with\nany value, or to an empty string to remove it entirely.\n\nThe `a2s:link` option will wrap the target object with a clickable link to the\nURL specified in the value.\n\n#### Special references\n\nIt is possible to reference an object for formatting using its X and Y\ncoordinates. The coordinate system for ASCIIToSVG starts at (0, 0) in the top\nleft of the diagram.\n\nSuch references should only be made for stable diagrams, and only if you\n*really* need to style text or a line in some particular way. These references\nare marked by beginning the line with `[X,Y]` where `X` is the numeric row and \n`Y` is the numeric column of the object's top-left-most point.\n\n## Unsupported features\n\nThe Go implementation does not yet support all the features of the PHP version.\nFeatures that are currently unimplemented include:\n\n * Custom objects, including the `a2s:type` format specifier, are not yet\n implemented.\n * No support is planned for angled corners using `#`.\n * No support is planned for undirected lines using `*`.\n\n## External Resources\n\nThere are some interesting sites that you might be interested in; these are\nmildly related to the goals of ASCIIToSVG:\n\n * [ditaa][1] (previously mentioned) is a Java utility with a very similar\n   syntax that translates ASCII diagrams into PNG files.\n * [App::Asciio][3] (previously mentioned) allows you to programmatically\n   draw ASCII diagrams.\n * [Asciiflow][5] is a web front-end to designing ASCII flowcharts.\n\nIf you have something really cool that is related to ASCIIToSVG, and I have\nfailed to list it here, do please let me know.\n\n\n\n[1]: http://ditaa.sourceforge.net/ \"ditaa - DIagrams Through ASCII Art\"\n[2]: http://mtrack.wezfurlong.org/ \"mtrack project management software\"\n[3]: http://search.cpan.org/dist/App-Asciio/lib/App/Asciio.pm \"App::Asciio\"\n[4]: http://www.w3.org/TR/SVG/paths.html \"SVG Paths\"\n[5]: http://www.asciiflow.com/ \"Asciiflow\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasciitosvg%2Fasciitosvg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasciitosvg%2Fasciitosvg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasciitosvg%2Fasciitosvg/lists"}