{"id":20713874,"url":"https://github.com/diffplug/freshmark","last_synced_at":"2025-04-23T08:07:47.928Z","repository":{"id":57718792,"uuid":"42576717","full_name":"diffplug/freshmark","owner":"diffplug","description":"Keep your markdown fresh","archived":false,"fork":false,"pushed_at":"2023-02-05T07:53:36.000Z","size":572,"stargazers_count":21,"open_issues_count":1,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-23T08:07:42.069Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/diffplug.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-09-16T09:07:39.000Z","updated_at":"2023-04-11T10:11:00.000Z","dependencies_parsed_at":"2023-02-18T22:30:19.380Z","dependency_job_id":null,"html_url":"https://github.com/diffplug/freshmark","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diffplug%2Ffreshmark","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diffplug%2Ffreshmark/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diffplug%2Ffreshmark/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diffplug%2Ffreshmark/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/diffplug","download_url":"https://codeload.github.com/diffplug/freshmark/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250395282,"owners_count":21423400,"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-11-17T02:27:51.380Z","updated_at":"2025-04-23T08:07:47.889Z","avatar_url":"https://github.com/diffplug.png","language":"Java","readme":"# \u003cimg align=\"left\" src=\"freshmark.png\"\u003e FreshMark: Keep your markdown fresh\n\u003c!---freshmark shields\noutput = [\n\tlink(shield('Maven artifact', 'mavenCentral', '{{group}}:{{name}}', 'blue'), 'https://bintray.com/{{org}}/opensource/{{name}}/view'),\n\tlink(shield('Latest version', 'latest', '{{stable}}', 'blue'), 'https://github.com/{{org}}/{{name}}/releases/latest'),\n\tlink(shield('Javadoc', 'javadoc', 'OK', 'blue'), 'https://{{org}}.github.io/{{name}}/javadoc/{{stable}}/'),\n\tlink(shield('License Apache', 'license', 'Apache', 'blue'), 'https://tldrlegal.com/license/apache-license-2.0-(apache-2.0)'),\n\t'',\n\tlink(shield('Changelog', 'changelog', '{{version}}', 'brightgreen'), 'CHANGES.md'),\n\tlink(image('Travis CI', 'https://travis-ci.org/{{org}}/{{name}}.svg?branch=master'), 'https://travis-ci.org/{{org}}/{{name}}'),\n\tlink(shield('Live chat', 'gitter', 'chat', 'brightgreen'), 'https://gitter.im/{{org}}/{{name}}'),\n\t'',\n\tlink(shield('Gradle', 'Works with', 'Gradle', 'ff69b4'), '#gradle'),\n\tlink(shield('Console', 'Works with', 'Console', 'ff69b4'), '#console'),\n\tlink(shield('Java API', 'Works with', 'Java API', 'ff69b4'), '#java-api'),\n\tlink(shield('Contribute', 'Works with', 'CONTRIBUTIONS WELCOME', 'ff69b4'), '#how-to-run-it'),\n\t].join('\\n')\n--\u003e\n[![Maven artifact](https://img.shields.io/badge/mavenCentral-com.diffplug.freshmark%3Afreshmark-blue.svg)](https://bintray.com/diffplug/opensource/freshmark/view)\n[![Latest version](https://img.shields.io/badge/latest-1.3.1-blue.svg)](https://github.com/diffplug/freshmark/releases/latest)\n[![Javadoc](https://img.shields.io/badge/javadoc-OK-blue.svg)](https://diffplug.github.io/freshmark/javadoc/1.3.1/)\n[![License Apache](https://img.shields.io/badge/license-Apache-blue.svg)](https://tldrlegal.com/license/apache-license-2.0-(apache-2.0))\n\n[![Changelog](https://img.shields.io/badge/changelog-1.4.0--SNAPSHOT-brightgreen.svg)](CHANGES.md)\n[![Travis CI](https://travis-ci.org/diffplug/freshmark.svg?branch=master)](https://travis-ci.org/diffplug/freshmark)\n[![Live chat](https://img.shields.io/badge/gitter-chat-brightgreen.svg)](https://gitter.im/diffplug/freshmark)\n\n[![Gradle](https://img.shields.io/badge/Works_with-Gradle-ff69b4.svg)](#gradle)\n[![Console](https://img.shields.io/badge/Works_with-Console-ff69b4.svg)](#console)\n[![Java API](https://img.shields.io/badge/Works_with-Java_API-ff69b4.svg)](#java-api)\n[![Contribute](https://img.shields.io/badge/Works_with-CONTRIBUTIONS_WELCOME-ff69b4.svg)](#how-to-run-it)\n\u003c!---freshmark /shields --\u003e\n\nGenerating URL's for the buttons above is tricky.  Once they're generated, it's hard to keep them up-to-date as new versions are released.  FreshMark solves the \"Markdown with variables\" problem by embedding tiny JavaScript scripts into the comments of your Markdown, which statically generate the rest of the document.  By running these scripts as part of your build script, your project's documentation will always stay up-to-date.\n\nHere is what the code looks like for the shields at the top of this document:\n\n```javascript\n\u003c!---freshmark shields\noutput = [\n\tlink(shield('Maven artifact', 'mavenCentral', '{{group}}:{{name}}', 'blue'), 'https://bintray.com/{{org}}/opensource/{{name}}/view'),\n\tlink(shield('Latest version', 'latest', '{{stable}}', 'blue'), 'https://github.com/{{org}}/{{name}}/releases/latest'),\n\tlink(shield('Javadoc', 'javadoc', 'OK', 'blue'), 'https://{{org}}.github.io/{{name}}/javadoc/{{stable}}/'),\n\tlink(shield('License Apache', 'license', 'Apache', 'blue'), 'https://tldrlegal.com/license/apache-license-2.0-(apache-2.0)'),\n\t].join('\\n')\n--\u003e\n[![Maven artifact](https://img.shields.io/badge/mavenCentral-com.diffplug.freshmark%3Afreshmark-blue.svg)](https://bintray.com/diffplug/opensource/freshmark/view)\n[![Latest version](https://img.shields.io/badge/latest-1.3.1-blue.svg)](https://github.com/diffplug/freshmark/releases/latest)\n[![Javadoc](https://img.shields.io/badge/javadoc-OK-blue.svg)](https://diffplug.github.io/freshmark/javadoc/1.3.1/)\n[![License Apache](https://img.shields.io/badge/license-Apache-blue.svg)](https://tldrlegal.com/license/apache-license-2.0-(apache-2.0))\n\u003c!---freshmark /shields --\u003e\n```\n\nIn addition to generating Markdown from scratch, FreshMark can also modify existing Markdown.  This ensures that any inline documentation links stay fresh.\n\n```javascript\n\u003c!---freshmark javadoc\noutput = prefixDelimiterReplace(input, 'https://{{org}}.github.io/{{name}}/javadoc/', '/', stable)\n--\u003e\nTo run FreshMark on some text, call [FreshMark.compile()](https://diffplug.github.io/freshmark/javadoc/1.3.1/com/diffplug/freshmark/FreshMark.html)\n\u003c!---freshmark /javadoc --\u003e\n```\n\n## How it works\n\nFreshMark has three pieces, `SECTION`, `SCRIPT`, and `BODY`.  They are parsed as shown below:\n\n```javascript\n\u003c!---freshmark SECTION\nvar javascript_here = 'this will be {{templated}} then executed as javascript';\n// this particular freshmark script doesn't modify the body at all\noutput = input;\n--\u003e\nBODY (markdown)\n\u003c!---freshmark /SECTION --\u003e\n```\n\nWhen `SCRIPT` is run, there are two magic variables:\n\n* `input` - This is everything inside of BODY (guaranteed to have only unix newlines at runtime)\n* `output` - The script must assign to this variable.  FreshMark will generate a new string where the `BODY` section has been replaced with this value.\n\nOnly four functions are provided:\n\n* `link(text, url)` - returns a markdown link\n* `image(altText, url)` - returns a markdown image\n* `shield(altText, subject, status, color)` - returns a markdown image generated by [shields.io](http://shields.io/).\n* `prefixDelimReplace(input, prefix, delimiter, replace)` - updates URLs which contain version numbers.\n\t* example: for parameters `prefix='http://website/', delimiter='/', replace='2.0'`\n\t* input `[entry point](http://website/1.2/docs/entryPoint)` would be transformed into `[entry point](http://website/2.0/docs/entryPoint)`\n\nIt's full ECMAScript 5.1, so you can define any other functions you like, but these should be all you need.\n\nWhen you run FreshMark, you can supply it with a map of key-value pairs using the command line or via a properties file.  If you're running FreshMark from a build system plugin such as Gradle, then all of your project's metadata will automatically be supplied.  These key-value pairs are used in the following way:\n\n* Before `SCRIPT` is executed, any `{{key}}` templates will be substituted with their corresponding value.\n* When `SCRIPT` is executed, all of these key-value pairs are available as variables.\n\n## How to run it\n\nAt the moment, you can run FreshMark using [Gradle](#gradle), the [console](#console), or the [Java API](#java-api) directly.  If you need a different way to run FreshMark, build it and submit a PR!  We'd be happy to help [in Gitter](https://gitter.im/diffplug/freshmark).\n\n### Gradle\n\nIntegration with Gradle is provided through the [Spotless](https://github.com/diffplug/spotless) plugin.  Spotless can also enforce lots of style rules as well (tab vs space, Java import ordering, etc), but it's completely a-la-carte.  To just apply FreshMark to all of the markdown in your project (and nothing else), simply add this to your `build.gradle`:\n\n```groovy\nplugins {\n\tid 'com.diffplug.gradle.spotless' version '1.3.1'\n}\n\nspotless {\n\tfreshmark {}\n}\n```\n\nSee the [spotless docs](https://github.com/diffplug/spotless) for more details.\n\n### Console\n\nThis repo is a command line application.  Just run `freshmark.bat` (Windows) or `freshmark` (Linux and Mac) to run it.\n\n```\nusage: freshmark [-P key=value] [-properties FILE] [-endings [PLATFORM_NATIVE | WINDOWS | UNIX]] -file FILE\n-P                                     : sets the properties which are available in the script, -P KEY_1=VALUE_1 -P KEY_2=VALUE_2\n-properties FILE                       : loads properties from the given file\n-endings [PLATFORM_NATIVE | WINDOWS |  : determines the line endings to use in the output (default: PLATFORM_NATIVE)\n-file FILE                             : applies freshmark to the given file (multiple are allowed)\n```\n\n### Java API\n\nIt's a very small [package](src/main/java/com/diffplug/freshmark).  If you want to add more functions, change which variables are there, make the behavior depend on the section name, etc, just take a peek at [FreshMark.java](src/main/java/com/diffplug/freshmark/FreshMark.java).  If you want to build some other kind of \"comment language\" (generating sections of a document by embedding scripts in its comments) take a look at [CommentScript.java](https://github.com/diffplug/freshmark/blob/master/src/main/java/com/diffplug/freshmark/CommentScript.java) - it's not specific to markdown or HTML-style comments.\n\n## Acknowledgements\n* Scripts run by [JScriptBox](https://github.com/diffplug/jscriptbox).\n* Bugs found by [findbugs](http://findbugs.sourceforge.net/), [as such](https://github.com/diffplug/durian-rx/blob/v1.0/build.gradle?ts=4#L92-L116).\n* Scripts in the `.ci` folder are inspired by [Ben Limmer's work](http://benlimmer.com/2013/12/26/automatically-publish-javadoc-to-gh-pages-with-travis-ci/).\n* Built by [gradle](http://gradle.org/).\n* Tested by [junit](http://junit.org/).\n* Maintained by [DiffPlug](http://www.diffplug.com/).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiffplug%2Ffreshmark","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdiffplug%2Ffreshmark","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiffplug%2Ffreshmark/lists"}