{"id":13398245,"url":"https://github.com/zeromq/gitdown","last_synced_at":"2025-03-01T18:24:41.224Z","repository":{"id":1087300,"uuid":"938274","full_name":"zeromq/gitdown","owner":"zeromq","description":"Turn github into your publishing platform","archived":false,"fork":false,"pushed_at":"2017-06-02T05:16:36.000Z","size":488,"stargazers_count":131,"open_issues_count":3,"forks_count":48,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-07-30T19:15:42.569Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Perl6","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zeromq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2010-09-25T12:05:47.000Z","updated_at":"2024-04-19T02:41:28.000Z","dependencies_parsed_at":"2022-07-06T06:31:03.832Z","dependency_job_id":null,"html_url":"https://github.com/zeromq/gitdown","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/zeromq%2Fgitdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeromq%2Fgitdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeromq%2Fgitdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeromq%2Fgitdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zeromq","download_url":"https://codeload.github.com/zeromq/gitdown/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241406030,"owners_count":19957941,"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":[],"created_at":"2024-07-30T19:00:20.878Z","updated_at":"2025-03-01T18:24:41.180Z","avatar_url":"https://github.com/zeromq.png","language":"Perl6","funding_links":[],"categories":["Perl6","others"],"sub_categories":[],"readme":"\n\u003ccenter\u003e\n\u003cimg src=\"https://github.com/imatix/gitdown/raw/master/images/README_1.png\" alt=\"1\"\u003e\n\u003c/center\u003e\n\n\u003cA name=\"toc1-17\" title=\"Welcome To Gitdown\"\u003e\u003c/A\u003e\nWelcome To Gitdown\n==================\n\nGitdown is a simple tool for writing documentation hosted on a github repository.  It uses [ditaa][] to convert ascii diagrams into images, and produces [markdown][] documents that can be uploaded to your repository along with code.  I made Gitdown so that we could write technical white papers and user guides as plain text (including diagrams) and publish them with a single \"git push\" command.  Gitdown is a simpler version of the tool we use to maintain the [ØMQ][zeromq] [Guide][zguide].\n\nGitdown is written and maintained by Pieter Hintjens.  Please use the issue [tracker][] for all comments and errata.  This document was published on Thursday February, 2017 at 20:23:49, and generated by the magic of Gitdown from README.txt.\n\nThis is version 2011.03.24 of Gitdown. Changelog:\n\n* 2013.02.05: Gyepi Sam changed pull command to make chunk specification optional.\n* 2010.03.24: added .pull command to include chunks from other files.\n* 2010.10.11: don't do symbol substitution in code blocks.\n* 2010.10.09: added .toc token to generate table of contents.\n\n\u003cA name=\"toc2-32\" title=\"Contents\"\u003e\u003c/A\u003e\nContents\n--------\n\n*  \u003ca href=\"#toc2-38\"\u003eLicense\u003c/a\u003e\n*  \u003ca href=\"#toc2-47\"\u003eInstallation and Use\u003c/a\u003e\n*  \u003ca href=\"#toc2-81\"\u003eInstallation in Cygwin\u003c/a\u003e\n*  \u003ca href=\"#toc2-105\"\u003eHow it Works\u003c/a\u003e\n*  \u003ca href=\"#toc2-160\"\u003eGitdown Syntax Summary\u003c/a\u003e\n*  \u003ca href=\"#toc2-226\"\u003eMarkdown Syntax Summary\u003c/a\u003e\n\n\u003cA name=\"toc2-38\" title=\"License\"\u003e\u003c/A\u003e\nLicense\n-------\n\nCopyright (c) 2010-2011 Pieter Hintjens\nCopyright (c) 1996-2011 iMatix Corporation\n\nThis is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.\n\n\u003cA name=\"toc2-47\" title=\"Installation and Use\"\u003e\u003c/A\u003e\nInstallation and Use\n--------------------\n\nThe code is in the bin subdirectory.  Here is how I install it on a new box:\n\n    sudo cp bin/* /usr/local/bin\n    export PERLLIB=$PATH    #   goes into .bash_profile\n\nGitdown includes Ditaa/0.9 and assumes that Ditaa goes into /usr/local/bin/ditaa0_9.jar.\n\nAnother option is to leave the files in the git directory and install a wrapper script. \nAssuming the directory ~/bin exists and is in your path, you can do the following:\n\n    install-wrapper ~/bin\n\nto install the file ~/bin/gitdown, which will set things up to run correctly. \n\nGitdown assumes that these tools are already installed on your box, which is easy if you're running Linux:\n\n* *ImageMagick*, specifically `mogrify`.\n* *Perl*.\n* *Java*, a Java run-time environment is needed to run ditaa.\n\nTo use Gitdown, edit a text document much like this README.txt.  Then:\n\n    gitdown myfile.txt\n    git add myfile.md images/\n    git commit -m \"Hey, Gitdown is totally crazy!\"\n    git push origin master\n\nThe images directory holds images for all documents in the current directory.  You can write documents anywhere on the git tree but if they are not at the root you must tell Gitdown how to create a full image path by setting the SUBDIR symbol (see below).\n\n\n\u003cA name=\"toc2-81\" title=\"Installation in Cygwin\"\u003e\u003c/A\u003e\nInstallation in Cygwin\n----------------------\n\nInstall apt-cyg - cygwin package manager:\n\n      lynx -source rawgit.com/transcode-open/apt-cyg/master/apt-cyg \u003e apt-cyg\n      install apt-cyg /bin\n\nInstall ImageMagick:\n\n      apt-cyg install ImageMagick\n      \nDownload and install Java JDK from [here](http://www.oracle.com/technetwork/java/javase/downloads/index.html), then restart your PC for the env vars to reflect\n\nCopy the binaries to /usr/local/bin:\n\n      cp bin/* to /usr/local/bin\n\nAdd this to your ~/.bash_profile:\n\n      export PERLLIB=$PATH\n    \n\n\u003cA name=\"toc2-105\" title=\"How it Works\"\u003e\u003c/A\u003e\nHow it Works\n------------\n\nGitdown exploits github.com's willingness to serve image blobs and Markdown documents that refer to them.  This means you can publish a document with correctly-formatted links, together with images, in a single Git operation.  It is a neat and comfortable way to work.  Kudos to Stathis Sideris for making Ditaa.  Gitdown also adds a preprocessing layer for symbolic insertion and simple macros like 'table of contents'.  This code was recycled from [htmlpp](https://imatix-legacy.github.io/htmlpp/), a HTML preprocessor that looked a lot like Markdown.\n\nThe Gitdown workflow is:\n\n\u003ccenter\u003e\n\u003cimg src=\"https://github.com/imatix/gitdown/raw/master/images/README_2.png\" alt=\"2\"\u003e\n\u003c/center\u003e\n\n1. You edit a text file that contains text and diagrams in a single document.\n2. You process this document with Gitdown to give a Markdown document plus a number of images in an images subdirectory.\n3. You add the output (Markdown and images) to your commit set and push that to the repository.\n4. The Markdown document is now readable, with images, via the github.com user interface.\n\nThis README acts as an example.\n\n\u003cA name=\"toc2-160\" title=\"Gitdown Syntax Summary\"\u003e\u003c/A\u003e\nGitdown Syntax Summary\n---------------------\n\nGitdown is a pre-processor that adds these syntax elements on top of Markdown:\n\n    [diagram]                   Defines a ditaa diagram block\n    [/diagram]                  # represents diagram number 1..n\n\n    .- comment                  Comment line\n    .set name=value             Sets Gitdown symbol\n    .sub oldval=newval          Replaces oldval by newval in every line\n    .toc [top]                  Insert table of contents\n    .pull srcfile[@tag][,opts]  Pull a chunk of text, or the whole file, from srcfile\n    .end                        Everything past this is ignored\n\n    $\\(xxx)                     Value of variable, anywhere in text\n    $\\(xxx?zzz)                 Value of variable, or zzz if undefined\n    %\\(text?zzz)                Value of environment variable, or zzz if undef\n    \u0026abc\\(text)                 Intrinsic function with arguments\n\n    time()                      Format current time as hh:mm:ss\n    date()                      Return current date value\n    date(\"picture\")             Format current date using picture\n    date(\"picture\", date, lc)   Format specified date using picture \u0026 language\n    week_day([date])            Get day of week, 0=Sunday to 6=Saturday\n    year_week([date])           Get week of year, 1 is first full week\n    julian_date([date])         Get Julian date for date\n    lillian_date([date])        Get Lillian date for date\n    date_to_days(date)          Convert yyyymmdd to Lillian date\n    days_to_date(days)          Convert Lillian date to yyyymmdd\n    future_date(days[,date])    Calculate a future date\n    past_date(days[,date])      Calculate a past date\n    date_diff(date1[,date2])    Calculate date1 - date2\n    image_height(\"image.ext\")   Get image height (GIF, JPEG)\n    image_width(\"image.ext\")    Get image width (GIF, JPEG)\n    file_size(\"filename\",arg)   Get size of file: optional arg K or M\n    file_date(\"filename\")       Get date of file\n    file_time(\"filename\")       Get time of file as hh:mm:ss\n    normalise(\"filename\")       Normalise filename to UNIX format\n    system(\"command\")           Call a system utility\n    lower(\"string\")             Convert string to lower case\n    upper(\"string\")             Convert string to upper case\n\nThe top argument for .toc tells it the top header level in the text. Lower levels are shown horizontally.  E.g. this file has level 2 headers in the text and uses `.toc 1` to get these laid-out on a single row.\n\nIf the .pull command includes an optional @tag, the named chunk of text is pulled from the source file.\nA chunk of text is identified by '@tag' anywhere in the line before the chunk, and any other tag signalling the end. '@end' can be used to close any chunk. Tag names must be alphanumeric.\nIf @tag is omitted, the entire file is included.\n\nThe opts argument for .pull can be: 'code' to indicate the results should be indented 4 spaces.\nAn opts of 'left' removes any left margin.\n\n\nThese symbols have special meaning:\n\n* GIT defines the root HTTP URL of the git repository.\n* BRANCH defines the respository branch, defaults to 'master'.\n* SUBDIR defines the sub/dir/ to the current file, if not empty, should end in / if not empty.\n\nThese symbols are predefined by gitdown for you:\n\n* INPUT specifies the original input file name.\n* SELF specifies the input file name without extension.\n* OUTPUT specifies the current output file name,\n\n\u003cA name=\"toc2-226\" title=\"Markdown Syntax Summary\"\u003e\u003c/A\u003e\nMarkdown Syntax Summary\n-----------------------\n\nThis is an extract of the most useful Markdown syntax.\n\n    # Header 1              or follow by ===== on next line\n    ## Header 2             or follow by ----- on next line\n    ### Header 3\n    #### Header 4\n\n    \u003e Blockquote            can continue over multiple lines\n    * List item             can continue over multiple lines\n    1. List item            can continue over multiple lines\n\n        code block          indented 4 spaces\n\n    \u003curl\u003e                   automatic link, e.g. \u003cph@imatix.com\u003e\n    ![alt](url)             image link\n    [text](url)             inline link\n    [text][]                implicit reference link\n      [text]: url           defined later in document\n\n    *emphasis*              usually, italics\n    **strong**              usually, bold\n    `Code`                  fixed-space font\n\n* You can put HTML anywhere in your text.\n* Blank lines separate paragraphs.\n* For more details see the [markdown][] syntax page.\n\n[zeromq]:       http://www.zeromq.com\n[zguide]:       http://zguide.zeromq.org\n[tracker]:      https://github.com/imatix/gitdown/issues\n[markdown]:     http://daringfireball.net/projects/markdown/syntax\n[ditaa]:        http://ditaa.org\n\n_This documentation was generated from gitdown/README.txt using [Gitdown](https://github.com/zeromq/gitdown)_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeromq%2Fgitdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzeromq%2Fgitdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeromq%2Fgitdown/lists"}