{"id":26781684,"url":"https://github.com/pixelunion/pangolin","last_synced_at":"2025-04-19T13:40:47.330Z","repository":{"id":33242535,"uuid":"36886874","full_name":"pixelunion/Pangolin","owner":"pixelunion","description":"Build better Tumblr themes","archived":false,"fork":false,"pushed_at":"2016-09-20T20:14:34.000Z","size":132,"stargazers_count":102,"open_issues_count":0,"forks_count":6,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-03-29T08:17:26.600Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/pixelunion.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-06-04T18:01:42.000Z","updated_at":"2021-05-11T17:08:52.000Z","dependencies_parsed_at":"2022-08-17T22:45:27.933Z","dependency_job_id":null,"html_url":"https://github.com/pixelunion/Pangolin","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/pixelunion%2FPangolin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixelunion%2FPangolin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixelunion%2FPangolin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixelunion%2FPangolin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pixelunion","download_url":"https://codeload.github.com/pixelunion/Pangolin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249704669,"owners_count":21313178,"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":"2025-03-29T08:17:31.694Z","updated_at":"2025-04-19T13:40:47.313Z","avatar_url":"https://github.com/pixelunion.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](https://cl.ly/2q3Q2Y0B0T0Y/pangolin-mark.svg)  \n# Pangolin\n\n**[Pixel Union](https://www.pixelunion.net)**'s very own Tumblr theme skeleton and build system, now open to everyone. Pangolin was built to help facilitate the rapid development of themes for the Tumblr platform. It provides a heavily opinionated suite of tools for every stage of the project.\n\nPangolin also includes pre-built functionality for [Open Graph](http://ogp.me) meta, Disqus and Facebook commenting, Google Analytics integration, Apple touch icons, 20+ social accounts, live load and click-to-load posts, [support for a marketing script](#marketing-helper), and so much more. :)\n\n## Our Stack\n\n#### Ruby\n\nFor overall asset watching, compiling, and serving. [Middleman](https://middlemanapp.com/) is used to serve styles and scripts, and a variety of Ruby helpers are used for templating and Tumblr settings.\n\n#### Slim\n\nWe preprocess our HTML using [Slim](http://slim-lang.com).\n\n#### CoffeeScript\n\nWe prefer [CoffeeScript](http://coffeescript.org) for JavaScript preprocessing. Additionally, we use class-based [Backbone](http://backbonejs.org) (+ [jQuery](https://jquery.com) and [Underscore](http://underscorejs.org)) for MVC. Views are available for Instagram, Flickr, and Twitter feeds.\n\n#### SCSS\n\nWe preprocess CSS with SCSS and [Compass](http://compass-style.org). By default, [Normalize.css](http://necolas.github.io/normalize.css/) is used for cross-browser style resets.\n\n#### PXU Photoset Extended\n\nAdditionally, the [PXU Photoset Extended](https://github.com/PixelUnion/Extended-Tumblr-Photoset) plugin is included in the source for custom Tumblr photosets.\n\n\n## Theme Development\n\nTo get started on a new or existing Tumblr theme, use the following steps.\n\n1. Clone this repo in to a new folder (or the repo of an existing theme).\n2. `bundle install` to pull in the required gems.\n3. Set the theme name in `config.rb`. (Not required if you're working on an existing theme.)\n4. Start the development server with `bundle exec rake server`.\n\nDevelop! Middleman is now serving your CSS at [http://localhost:4567/styles/style.css](http://localhost:4567/styles/style.css) and your JavaScript at [http://localhost:4567/scripts/script.js](http://localhost:4567/scripts/script.js).\n\nBecause Tumblr doesn't support local theme development, you will need to paste the theme code in to your theme's Customize HTML area each time you change the markup. You can copy the theme code to your clipboard on every `.slim` file change with `bundle exec rake auto_build`.\n\n**Note:** Tumblr now enforces assets to be served over HTTPS when in the Customize Theme screen, which Middleman does not do. This means that, for the moment, you won't be able to develop and live-customize your theme at the same time.\n\n## Rake Tasks\n\nThe following Ruby rake commands are available for building the theme files.\n\n- `bundle exec rake server` runs the Middleman development server at port 4567. It auto-builds and serves static assets for \"local\" development.\n- `bundle exec rake auto_build` automatically builds the development file and copies it to the clipboard when any slim file is changed.\n- `bundle exec rake build` builds all files, including assets. This minifies the styles and scripts.\n- `bundle exec rake build_development` builds the development theme file and copies it to clipboard.\n- `bundle exec rake build_production` builds only the production theme file.\n\n## config.rb\n\nUse `config.rb` to configure your development environment and theme settings.\n\n#### `theme` and `version`\n\nThese are used when creating the theme's build filename (for example, `mytheme-v1.0.0.html`), the masthead (generated in `lib/theme_helpers.rb`), and in the footer.\n\n#### `style_url` and `script_url`\n\nAfter making changes to styles or scripts, you will need to upload the assets to Tumblr's [static asset CDN](https://www.tumblr.com/themes/upload_static_file). Once uploaded, update these two variables and build out the theme file. Your local static assets can be found at `your-theme/build/scripts|styles`.\n\n#### `developer_name`, `developer_url`, and `purchase_url`\n\nThese are used in both the masthead and footer for informative and marketing purposes.\n\n#### `demo_url` and `marketing_url`\n\nBoth of these variables are used in a `themeInfo` object. `marketing_url` should point to a script that can be injected on the page for marketing purposes. See [Marketing Helper](#marketing-helper) for more information.\n\n## Ruby Helpers\n\n#### `theme_header`\n\n  Inserts a masthead into the code, with the theme name and version from `config.rb`.\n\n#### `block`\n\n  A helper for inserting Tumblr blocks into the code. Usage:\n\n  ```\n== block 'PreviousPage' do\n  a.previous href=\"{PreviousPage}\" {lang:Newer}\n  ```\n\n  will output:\n\n  ```\n{block:PreviousPage}\u003ca class=\"previous\" href=\"{PreviousPage}\"\u003elang:Newer\u003c/a\u003e{/block:PreviousPage}\n  ```\n\n#### \u003cdiv id=\"tumblroptions\"\u003e`TumblrOptions`\u003c/div\u003e\n\nThis provides a nice way to handle Tumblr's customize screen options. For in-depth usage see the `_TumblrOptions.slim` partial. The `add` method adds an option with the given type, name, and optionally a default value. The `:output` option determines whether or not a text option will be rendered literally by the `to_tumblr_json` method (which will break if the text option contains single quotes).\n\n  The `to_tumblr_json` method outputs all the options added to the instance so far as a javascript object, inside of script tags. It becomes available as Theme.options.\n\n## The `Theme` object\n\nBy default, `theme` is instantiated as a new `Theme` object. This object contains everything that powers the theme's core JavaScript on the page. Here's a run down of everything contained in the object:\n\n#### `*View` and `PostTypes.*View`\n\nAs Backbone is used as Pangolin's JavaScript framework, these members are methods used to instantiate new Backbone views. Found in: `source/scripts/theme.js` and `source/scripts/Theme/*View.js.coffee`.\n\n#### `helpers`\n\nVarious methods used to manipulate the page. Found in: `source/scripts/Theme/Helpers.js.coffee`.\n\n#### `options`\n\nContains all publicly accessible theme options. See the Ruby helper [TumblrOptions](#tumblroptions) for more information. Found in: `source/layouts/_TumblrOptions.slim`.\n\n## \u003cdiv id=\"marketing-helper\"\u003eMarketing Helper\u003c/div\u003e\n\nPixel Union has developed a custom script that, when injected in to the DOM and the user is viewing either the Customize page or Demo URL, displays a small marketing widget. You are welcome to build your own, but make sure you set `demo_url` and `marketing_url`.\n\n![Pixel Union's theme marketing widget](http://i.imgur.com/oqQuAuM.png?2)\n\nSee the source of `source/layouts/_MarketingWidget.slim` for more information.\n\n## Structure\n\n#### `index.html.slim`\n\n  This layout file contains the basic structure of the page (everything inside the `body` tags). It references quite a few partials (found in `layouts/`).\n\n#### `layouts/`\n\n  Other than `index.html.slim`, all the layouts are in this folder.\n\n  - `layout.slim` contains the \"outer\" portion of the theme, everything outside the `body` tags, plus the script inclusions that go at the end of the body.\n  - `_TumblrOptions.slim` contains all the customization screen options. Any JavaScript variables or CSS properties dependent on the customization options should be in here too.\n  - `_PermalinkContent.slim` contains comments, notes, and anything else that should only show on the permalink page.\n  - `_PostMeta.slim` contains commment counts, timestamps, and any other post metadata.\n  - `_Social.slim` contains the links to social media accounts.\n  - `_MarketingWidget.slim` is for the marketing widget that is displayed on theme demos and on the customization screen.\n  - `_OpenGraph.slim` contains the Open Graph meta for supporting Facebook sharing.\n\n#### `PostTypes/`\n\nThis folder contains the partial for each post type.\n\n#### `scripts/`\n\nThis folder contains all the JavaScript/CoffeeScript.\n\n- `script.js` contains the \"root\" script file. All it does is require the rest of the javascript: jQuery, Underscore.js, Backbone.js, the plugins, the theme code.\n- `libs/` stores any non-plugin JavaScript libraries in use.\n- `plugins.js` for requiring any jQuery plugins.\n- `plugins/` for storing any jQuery plugins.\n- `external-feeds/` contains CoffeeScript for social feeds.\n- `theme.js` just requires the Theme object and initializes the ThemeView.\n- `Theme/` contains all the theme code.\n\t- `ThemeView.js.coffee` is the \"root\" view that sets everything up. It checks some settings and gets things going.\n\t- `PostView.js.coffee` is the superclass of all our posts. It contains any functionality shared by all post types.\n\t- `PostTypes/*PostView.js.coffee` is the functionality specific to each post type.\n\t- `PostsView.js.coffee` handles setting up the post views, infinite scrolling, etc.\n\t- `Helpers.js.coffee` contains any utility functions that need to be added.\n\n#### `styles/`\n\nAll the stylesheets!\n\n- `style.css.scss` includes the normalize styles, the clearfix, and pulls in all the theme styles.\n- `_Theme.scss` includes the global theme styles and variables.\n- `_Mixins.scss` for handy mixins.\n- `_Post.scss` includes styles for all post types.\n- `PostTypes/` includes styles for each individual post type.\n- `extras/` for any additional styles. For example: the photoset plugin.\n\n## Special Thanks\n\nPangolin has been touched by nearly every developer to walk through Pixel Union's doors, but it wouldn't be where it is today without the help of [Jared Norman](https://github.com/jarednorman), [Gray Gilmore](https://github.com/graygilmore), and [Philip McLaughlin](https://github.com/audiophil).\n\n## Contributing\n\nWhen contributing to Pangolin, keep a few things in mind:\n\n- Take care to maintain the existing coding style, including indentation and naming conventions.\n- If updating styles or scripts, be sure to `build_production`, upload the respective stylesheet or script to Tumblr's [static asset CDN](https://www.tumblr.com/themes/upload_static_file), and update the URL within `config.rb`.\n- If updating markup, be sure to use the block helpers (`== block 'PreviousPage' do`) over standard Tumblr blocks (`{block:PreviousPage}...{/block:PreviousPage}`) when possible.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpixelunion%2Fpangolin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpixelunion%2Fpangolin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpixelunion%2Fpangolin/lists"}