Git Product home page Git Product logo

typograms's Introduction

typograms

Typograms (short for typographic diagrams) is a lightweight image format (text/typogram) useful for defining simple diagrams in technical documentation, originally developed here.

See it in action here:

https://google.github.io/typograms/

Like markdown, typograms is heavily inspired by pre-existing conventions found in ASCII diagrams. A small set of primitives and rules to connect them is defined, which you can use to build larger diagrams.

Typograms optimizes for editability and portability (e.g. plain text is easy to maintain, change, store and transmit), at the cost of expressivity (e.g. SVG is more expressive) and ergonomics (e.g. higher level tools produce diagrams faster).

You can embed typograms into pages using the JS rendering library:

<body>
  <script src="https://google.github.io/typograms/typograms.js"></script>
  <script type="text/typogram">
+----+
|    |---> My first diagram!
+----+
  </script>
</body>

A comparison with related work is available here.

typograms's People

Contributors

dharmeshgurnani avatar karlhorky avatar samuelgoto avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar

typograms's Issues

Text is misplaced & cut off in Firefox

In Firefox text rendered by the typogram js library is cut off at the top of each block & appears to be slightly misplaced vertically elsewhere:

Firefox:
image

image

Chrome:
image

image

(Chrome version 115.0.5790.170 (Official Build) (64-bit), Firefox 116.0.2 (64-bit))

Typogram images fail badly in dark mode

Currently, typogram's styles explicitly use black as the fill/stroke for all of its diagram bits. Since it also uses the default transparent bg for its generated <svg> element, this means that a page in dark mode sees black lines on the dark-mode background (generally black as well). You can see this in action at https://fedidcg.github.io/FedCM/#introduction (scroll down a little in the Introduction section). (I just submitted a PR overriding their styles to be darkmode-friendly, so depending on when you read this it's possible they've been fixed already. But you can just generate any diagram yourself and view it on a darkmode page.)

The easiest fix for this is to just change all those instance of black to currentcolor. This'll automatically adapt to the color scheme, and give users of the library a little bit of extra control if they wish.

React component for Typograms

First, thank you for the contribution with this project! It's helping me a lot on docs for my open source project. I'm using it with docusaurus and, after a few tweaks, I was able to make it run.

However, in order to do that I had to change the code on typograms.js to expose the function create as window.createTypogram.

Here is the React component:

import { v4 as uuidv4 } from 'uuid';
import React, { Component } from 'react';

class Typogram extends Component {
    constructor() {
        super()
        this.id = uuidv4()
    }

    componentDidMount() {
        const script = document.getElementById(this.id)
        if (!script) return
        const svg = window.createTypogram(script)
        script.parentNode.insertBefore(svg, script.nextSibling)

    }
    render() {
        return (
            <div style={{ textAlign: 'center' }}>
                <script id={this.id} type="text/typogram">
                    {this.props.children}
                </script>
            </div>
        )
    }
}

export default Typogram;

Maybe there are better ways to do it. Anyways, I think it would be great if instead of using DOMContentLoaded method, there should be another ways to use the lib, like exposing the internal functions.

Replace <pre> element contents instead of inserting after <script>

Issue based on this HackerNews comment by @chris-morgan: https://news.ycombinator.com/item?id=37048556

<script type="text/typogram">

This should use <pre> instead, e.g. <pre class="typogram">. It’s content, not scripting, and if the JavaScript isn’t run (for whatever reason—JS is less reliable than people often think, especially third-party JS, even on environments that don’t try to block it) you’d like the diagram to still be visible in some form.

My suggestion would be to use a custom data attributes (i.e. data-typogram) instead, but it might just be personal preference.

Retaining the <pre> would also be a great improvement for selecting text—the current arrangement of “place single-character <text> elements” is almost useless for copy and paste (losing spaces and line breaks), which is the main reason I can imagine wanting such a thing.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.