{"id":18378262,"url":"https://github.com/tyom/middleman-sculptor","last_synced_at":"2025-10-07T22:34:16.967Z","repository":{"id":29024430,"uuid":"32551718","full_name":"tyom/middleman-sculptor","owner":"tyom","description":"Middleman extension for sculpting styleguides","archived":false,"fork":false,"pushed_at":"2015-11-20T15:22:48.000Z","size":284,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-22T07:41:43.782Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"DarkMarmot/empty-machine","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tyom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-03-19T23:30:49.000Z","updated_at":"2016-05-18T20:53:27.000Z","dependencies_parsed_at":"2022-08-20T13:10:45.570Z","dependency_job_id":null,"html_url":"https://github.com/tyom/middleman-sculptor","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tyom%2Fmiddleman-sculptor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tyom%2Fmiddleman-sculptor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tyom%2Fmiddleman-sculptor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tyom%2Fmiddleman-sculptor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tyom","download_url":"https://codeload.github.com/tyom/middleman-sculptor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247563901,"owners_count":20958971,"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-06T00:32:37.618Z","updated_at":"2025-10-07T22:34:16.885Z","avatar_url":"https://github.com/tyom.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Middleman Sculptor\n\n[Middleman](https://middlemanapp.com/) extension for creation of interactive styleguides and code examples.\n\n## Installation\n\n    $ gem install middleman-sculptor\n\n## Usage\n\nMiddleman Sculptor has an excecutable `middleman-sculptor`. It is also aliased to `sculpt`.\n\nTo see the list of available commands run `sculpt help`. Sculptor extends [Middleman](https://github.com/middleman/middleman) so all Middleman commands also apply, although they currently do not appear under the `sculptor help` command.\n\n### New project\n\nTo start a new project:\n\n    $ middleman-sculptor init project-name\n\nThis will create a new directory `project-name` with templates for a new styleguide. It also installs Ruby and NPM dependencies.\n\nAliases: `i` and `n`.\n\n### Configuring external Sass load paths and assets\n\nMiddleman Sculptor uses [Webpack](https://webpack.github.io/) to bundle up its JavaScript. This allows writing JS in CommonJS or AMD style. Then JS is passed to Asset Pipiline to be served.\n\nTo use an NPM JS Library just `npm install` it and Webpack will pick it up. To use Sass library or make images discoverable by Asset Pipeline (e.g. [Mojular GOV.UK Elements](https://github.com/mojular/govuk-elements)) add relevant paths to `Sass.load_paths` and Sprockets in `config.rb`:\n\n```ruby\n# Sass load paths\ngovuk_elements_path = File.join(root, 'node_modules/mojular-govuk-elements')\nJSON.parse(IO.read(\"#{govuk_elements_path}/package.json\"))['paths']['sass'].each do |p|\n  Sass.load_paths \u003c\u003c File.expand_path(\"#{govuk_elements_path}/#{p}\")\nend\n\n# Sprockets\nready do\n  moj_images = File.join(root, 'node_modules', 'mojular-govuk-elements', 'assets', 'images')\n  sprockets.append_path moj_images\n\n  Dir.chdir(moj_images) do\n    Dir['**/*.{js,png,jpg}'].each do |asset|\n      sprockets.import_asset(asset)\n    end\n  end\nend\n```\n\n#### Project structure\n\nWhen Sculptor generates a new project it adds a few files and directories that are used for the styleguide UI. They are called or prefixed with the word *glyptotheque* and can be edited to customise the look and feel of the styleguide.\n\n### Existing project\n\nTo update Sculptor in an existing project run `middleman-sculptor init` in the project folder. It's recommended to have the existing project in a version control system so that any conflicting local changes can be easily reapplied.\n\n\n### Running local server\n\nBundle up JavaScript using Webpack:\n\n    $ node_modules/.bin/webpack\n\nOr install it globally `npm install -g webpack` and run using `webpack` command. You can leave it running in another terminal tab `webpack --watch`.\n\nDuring the development run local [Middleman server](https://middlemanapp.com/basics/development_cycle/):\n\n    $ middleman server\n\n`server` is optional and is the default command so can be omitted.\n\n*Recommended* way is to run both using [Foreman](https://github.com/ddollar/foreman) (included in Gemfile):\n\n    $ foreman start\n\nThis will launch Middleman server and Webpack watch together.\n\n\n## Creating a styleguide\n\nA styleguide is a collection of html snippets called **models**. Sculptor extends Middleman with several new helpers and templates that wrap these snippets.\n\nMiddleman supports a [number of templates](https://middlemanapp.com/basics/template_engine_options/) so any ERB, Haml or Slim should all work the same but it's mostly been tested with Slim.\n\nTo start, create a new page anywhere in `source` directory. It should have a [Frontmatter](https://middlemanapp.com/basics/frontmatter/) with at least one property `title`.\n\nLet's say we create a new page `source/button.html.slim`\n\n```slim\n---\ntitle: Button\n---\n\n= model\n  button Click me\n```\n\nNow if we run `middleman server` and go to http://localhost:4567/, we'll see a menu in the left-hand side sidebar with *Button* entry. There is also a box in the main section called *Button*. They both link to our new page.\n\n\u003cimg src=docs/styleguide-index.png width=800\u003e\n\nThe Button page shows the model, and toggles to show its source and structure outline.\n\n\u003cimg src=docs/styleguide-page.png width=800\u003e\n\nEach additional model will appear on the page and can be mixed with any other HTML. For example, documentation on usage of a particular component.\n\nNB: Due to the way Sculptor extracts models from template to make them accessible by URLs, some pages may require a server restart after they are added/renamed.\n\n\n## Adding stylesheets\n\nSculptor uses Sass by default but other CSS preprocessors or vanilla CSS can be used.\n\nStyles can be placed in the same directory as the HTML file, or in the `assets` directory. To ensure the styles properly integrate with the assets pipeline, it's recommended to place styles in the `assets/styles` directory or anywhere within the `source` directory as long as they are in subdirectory called `styles`. Then the Sass can correctly import other stylesheets (including external dependencies) and find images.\n\nLet's create a new stylesheet for our button. Create a new file `source/styles/generic.scss` with the following contents:\n\n```scss\nbutton {\n  padding: 20px;\n  background: #ddd;\n  font-size: 1em;\n  border: 0;\n}\n```\n\nTo include this stylesheet in the file add the `stylesheet` property to file's Frontmatter:\n\n```yaml\n---\ntitle: Button\nstylesheet: styles/generic\n---\n```\n\nThe path is relative to the file's location. It can also include relative paths (e.g. `../another-directory/style.scss`). To use `source` directory as root start path with `/` (e.g. `/styles/generic.scss`).\n\nThe property can also be called `stylesheets` and include a list of files, either comma-separated or list separated, e.g.:\n\n```yaml\nstylesheets: base, form, footer\n```\n\n```yaml\nstylesheets:\n  - base\n  - form\n  - footer\n```\n\n## Adding JavaScript\n\nSimilarly to styles, JS files can be injected.\n\n```yaml\njavascript: js/button.js\n```\n\n## Models\n\nEach page can contain any number of *models*, the extracts of HTML that are rendered on HTML page several treatments:\n\n- The snippet is rendered on HTML page in a special container  \n  \u003cimg src=docs/styleguide-model.png width=400\u003e  \n\n- It has an **Outline** toggle that shows the structure of the HTML snippet\n  \u003cimg src=docs/styleguide-outline.png width=400\u003e  \n\n- It has an **HTML Source** toggle that shows the HTML snippet code\n  \u003cimg src=docs/styleguide-html.png width=400\u003e  \n\nThere are two types of models: **inline** and **iframe**.\n\n### Inline models\n\nGood for rendering isolated components which styles are scoped in components selector and don't affect the rest of the page.\n\nThis is a standard model helper. It renders its contents and styles directly in the page.\n\n[Slim Template Language](https://github.com/slim-template/slim) also parses standard HTML which makes it great for quickly generating pages. Although currently Slim minifies rendered HTML. Slim also allows [embedding of other languages](https://github.com/slim-template/slim#embedded-engines-markdown-). I recommend embedding your code in `erb:`\n\n```slim\n= model\n  erb:\n    \u003ch1 class=\"page-title\"\u003eSculptor\u003c/h1\u003e\n```\n\nThis way the white spaces are preserved.\n\n### iframe models\n\nWhen the embedded styles or JS need to be encapsulated, use iframe model. It will render its contents in the iframe and resize appropriately.\n\nThe first parameter is required and used to generate a file for each model which is used as iframe source.\n\nThis model also adds an **isolate** button which links to those individual files, allowing you to view each component on its own without any of Sculptor's UI.\n\n```slim\n= model 'title',\n  iframe: true\n  erb:\n    \u003ch1 class=\"page-title\"\u003eSculptor\u003c/h1\u003e\n```\n\nOr using an alias:\n\n```slim\n= imodel 'title'\n  erb:\n    \u003ch1 class=\"page-title\"\u003eSculptor\u003c/h1\u003e\n```\n\n### Remote grab\n\nModel can also have a remote source.\n\n```slim\n= imodel 'bbc',\n  url: 'http://www.bbc.co.uk/',\n  css: '#h4weather'\n```\n\n- `url` points to any public webpage (JS is not loaded)  \n- `css` grabs only the specified CSS selector. If multiple elements match, they are all returned. To pick a specific element within multiple returned, select it by the 0-index (separate selector from index by at least 1 space): `css: 'h2 #2'`\n\nIt's also possible to include remote CSS and JS.\n\n```yaml\n---\nstylesheet: http://static.bbci.co.uk/h4weather/0.82.2/style/h4weather.css\njavascript: http://code.jquery.com/jquery-2.1.4.min.js\n---\n```\n\n---\n\n### Examples\n\n- [Playground for GOV.UK elements](http://ministryofjustice.github.io/bower-playground/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftyom%2Fmiddleman-sculptor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftyom%2Fmiddleman-sculptor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftyom%2Fmiddleman-sculptor/lists"}