{"id":18889730,"url":"https://github.com/middleman/middleman-syntax","last_synced_at":"2025-05-16T04:06:06.502Z","repository":{"id":4690192,"uuid":"5837047","full_name":"middleman/middleman-syntax","owner":"middleman","description":"Code syntax highlighting plugin via Rouge for Middleman","archived":false,"fork":false,"pushed_at":"2025-04-07T09:37:25.000Z","size":103,"stargazers_count":179,"open_issues_count":1,"forks_count":58,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-05-12T16:15:28.867Z","etag":null,"topics":["code-highlight","middleman-extension","syntax-highlighting"],"latest_commit_sha":null,"homepage":"https://middlemanapp.com","language":"Ruby","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/middleman.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-09-17T06:19:18.000Z","updated_at":"2025-04-07T09:36:37.000Z","dependencies_parsed_at":"2024-04-29T06:45:17.661Z","dependency_job_id":null,"html_url":"https://github.com/middleman/middleman-syntax","commit_stats":{"total_commits":84,"total_committers":23,"mean_commits":3.652173913043478,"dds":0.6547619047619048,"last_synced_commit":"d1b3edd4d2a5ad1028621f6c03ab709a1d94d4e2"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/middleman%2Fmiddleman-syntax","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/middleman%2Fmiddleman-syntax/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/middleman%2Fmiddleman-syntax/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/middleman%2Fmiddleman-syntax/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/middleman","download_url":"https://codeload.github.com/middleman/middleman-syntax/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254464895,"owners_count":22075570,"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":["code-highlight","middleman-extension","syntax-highlighting"],"created_at":"2024-11-08T07:50:30.850Z","updated_at":"2025-05-16T04:06:06.464Z","avatar_url":"https://github.com/middleman.png","language":"Ruby","readme":"# Middleman-Syntax\n\n`middleman-syntax` is an extension for the [Middleman] static site generator that adds syntax highlighting via [Rouge](https://github.com/jayferd/rouge).\n\n[![Gem Version](https://badge.fury.io/rb/middleman-syntax.svg)][gem]\n[![CI](https://github.com/middleman/middleman-syntax/actions/workflows/ci.yml/badge.svg)](https://github.com/middleman/middleman-syntax/actions/workflows/ci.yml)\n[![Code Quality](https://codeclimate.com/github/middleman/middleman-syntax.svg)][codeclimate]\n\n## Installation\n\nIf you're just getting started, install the `middleman` gem and generate a new project:\n\n```bash\ngem install middleman\nmiddleman init MY_PROJECT\n```\n\nIf you already have a Middleman project, add `gem \"middleman-syntax\"` to your `Gemfile` and run `bundle install`.\n\n## Configuration\n\n```ruby\nactivate :syntax\n```\n\nYou can also pass options to Rouge:\n\n```ruby\nactivate :syntax, :line_numbers =\u003e true\n```\n\nYou can add extra css classes to the pre tag elements:\n\n```ruby\nactivate :syntax, :extra_css_classes =\u003e [\"custom-class\", \"another-class\"]\n```\n\nThis will add the extra css classes to the `\u003cpre\u003e` element in the generated HTML:\n\n```html\n\u003cdiv class=\"highlight\"\u003e\u003cpre class=\"highlight language-name custom-class another-class\"\u003e\u003ccode\u003e...\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\n```\n\nThe full set of options can be seen on your preview server's `/__middleman/config/` page.\n\n## Helper\n\nThe extension adds a new `code` helper to Middleman that you can use from your\ntemplates. It will  produce syntax-highlighted HTML wrapped in `\u003cpre\nclass=\"highlight language-name\"\u003e\u003ccode\u003e...html...\u003c/code\u003e\u003c/pre\u003e`.\n\nIn Erb, use `\u003c%` tags (not `\u003c%=` tags):\n\n```erb\n\u003c% code(\"ruby\") do %\u003e\ndef my_cool_method(message)\n  puts message\nend\n\u003c% end %\u003e\n```\n\n*Note:* In Haml, use `=`, not `-`:\n\n```haml\n= code('ruby') do\n  puts \"hello\"\n```\n\nFor more on Haml syntax, see the \"Haml\" section below.\n\nIn Slim:\n\n```slim\n= code('ruby') do\n  |\n    puts 'hello'\n```\n\nThe `code` helper supports [Rouge](https://github.com/jayferd/rouge) instance formatter options. These override the defaults set in your `config.rb`. Example options include:\n\n* `line_numbers`\n* `start_line`\n* `css_class`\n* `wrap`\n* `extra_css_classes`\n\nTo use these formatter options per code block, include them in a hash as the second argument. e.g.\n\n```erb\n\u003c% code(\"ruby\", :line_numbers =\u003e true, :start_line =\u003e 7) do %\u003e\ndef my_cool_method(message)\n  puts message\nend\n\u003c% end %\u003e\n```\n\nYou can also add extra css   classes to specific code blocks:\n\n```erb\n\u003c% code(\"ruby\", :extra_css_classes =\u003e [\"custom-class\", \"special\"]) do %\u003e\ndef my_cool_method(message)\n  puts message\nend\n\u003c% end %\u003e\n```\n\nThis will produce HTML like:\n```html\n\u003cdiv class=\"highlight\"\u003e\u003cpre class=\"highlight ruby custom-class special\"\u003e\u003ccode\u003e...\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\n```\n\n## CSS\n\nOn a default (i.e. unstyled) Middleman project, it will appear as if `middleman-syntax` isn't working, since obviously no CSS has been applied to color your code. You can use any Pygments-compatible stylesheet to style your code.\n\nYou can also let Rouge generate some CSS for you by creating a new stylesheet with a `.css.erb` extension in your Middleman project (at a path like `source/stylesheets/highlighting.css.erb`) with the contents:\n\n```erb\n\u003c%= Rouge::Themes::ThankfulEyes.render(:scope =\u003e '.highlight') %\u003e\n```\n\nAnd then include it in your layout or specific page by:\n\n```erb\n\u003c%= stylesheet_link_tag \"highlighting\" %\u003e\n```\n\nIf you want to include this in a larger Sass stylesheet, include it in your main stylesheet with `@import 'highlighting.css'`).\n\nRouge has `ThankfulEyes`, `Colorful`, `Github`, `Base16`, `Base16::Solarized`, `Base16::Monokai`, and `Monokai` themes.\n\n## Markdown\n\nThe extension also makes code blocks in Markdown produce highlighted code. Make sure you're using Redcarpet or Kramdown as your Markdown engine (in `config.rb`):\n\n```ruby\nset :markdown_engine, :redcarpet\nset :markdown, :fenced_code_blocks =\u003e true, :smartypants =\u003e true\n\n## OR\n\nset :markdown_engine, :kramdown\n```\n\nNow your Markdown will work just like it does [on GitHub](https://docs.github.com/en/get-started/writing-on-github) - you can write something like this with Redcarpet:\n\n\u003cpre\u003e\n```ruby\ndef my_cool_method(message)\n  puts message\nend\n```\n\u003c/pre\u003e\n\nYou can also disable the line numbers on a specific code block. However, this is Middleman-syntax specific feature, which only works when using Redcarpet.\n\nDisabling the line numbers on a code block:\n\n\u003cpre\u003e\n```ruby?line_numbers=false\ndef my_cool_method(message)\n  puts message\nend\n```\n\u003c/pre\u003e\n\nor with Kramdown:\n\n\u003cpre\u003e\n~~~ ruby\ndef my_cool_method(message)\n  puts message\nend\n~~~\n\u003c/pre\u003e\n\n## Haml\n\nWhen using Haml, a `:code` filter is exposed for outputting highlighted code. Because Haml filters don't allow arguments, you must use a special comment to indicate the language of the code to be highlighted (or let Rouge guess):\n\n```haml\n#example\n  :code\n    # lang: ruby\n\n    def foo\n      puts 'bar'\n    end\n```\n\nWith the special `# lang: \u003clanguage tag\u003e` comment on the first line, the `:code` filter is just like calling the `code` helper, but without the indentation problems that Haml might otherwise have. However, if you prefer, you can use the `code` helper along with the `:preserve` filter, as explained below.\n\n## Indentation Problems\n\nSome templating languages, like Haml, will indent your HTML for you,\nwhich will mess up code formatted in `\u003cpre\u003e` tags. When\nusing Haml, either use the `:code` filter (recommended), use the\n[`:preserve`](http://haml.info/docs/yardoc/file.REFERENCE.html#preserve-filter)\nfilter, or add `set :haml, { ugly: true }` in your `config.rb` to turn off\nHaml's automatic indentation.\n\nExample of using `:preserve`:\n\n```haml\n- code('ruby') do\n  :preserve\n    def foo\n      puts 'bar'\n    end\n```\n\n## Community\n\nThe official community forum is available at: http://forum.middlemanapp.com\n\n## Bug Reports\n\nGithub Issues are used for managing bug reports and feature requests. If you run into issues, please search the issues and submit new problems: https://github.com/middleman/middleman-syntax/issues\n\nThe best way to get quick responses to your issues and swift fixes to your bugs is to submit detailed bug reports, include test cases and respond to developer questions in a timely manner. Even better, if you know Ruby, you can submit [Pull Requests](https://help.github.com/articles/using-pull-requests) containing Cucumber Features which describe how your feature should work or exploit the bug you are submitting.\n\n## How to Run Cucumber Tests\n\n1. Checkout Repository: `git clone https://github.com/middleman/middleman-syntax.git`\n2. Install Bundler: `gem install bundler`\n3. Run `bundle install` inside the project root to install the gem dependencies.\n4. Run test cases: `bundle exec rake test`\n\n## Donate\n\n[Click here to lend your support to Middleman](https://github.com/sponsors/tdreyno)\n\n## License\n\nCopyright (c) 2012-2014 Benjamin Hollis. MIT Licensed, see [LICENSE] for details.\n\n[middleman]: http://middlemanapp.com\n[gem]: https://rubygems.org/gems/middleman-syntax\n[codeclimate]: https://codeclimate.com/github/middleman/middleman-syntax\n[LICENSE]: https://github.com/middleman/middleman-syntax/blob/master/LICENSE.md\n","funding_links":["https://github.com/sponsors/tdreyno"],"categories":["Features"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmiddleman%2Fmiddleman-syntax","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmiddleman%2Fmiddleman-syntax","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmiddleman%2Fmiddleman-syntax/lists"}