{"id":14967825,"url":"https://github.com/simbo/gulp-static-site-generator","last_synced_at":"2026-03-17T01:31:29.069Z","repository":{"id":54816973,"uuid":"50207787","full_name":"simbo/gulp-static-site-generator","owner":"simbo","description":"A static site generator for gulp supporting markdown, templates, pretty URLs and more.","archived":false,"fork":false,"pushed_at":"2021-01-27T13:06:05.000Z","size":64,"stargazers_count":7,"open_issues_count":3,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-01-31T10:51:12.003Z","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/simbo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-01-22T21:11:22.000Z","updated_at":"2021-01-27T12:23:36.000Z","dependencies_parsed_at":"2022-08-14T03:40:48.317Z","dependency_job_id":null,"html_url":"https://github.com/simbo/gulp-static-site-generator","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simbo%2Fgulp-static-site-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simbo%2Fgulp-static-site-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simbo%2Fgulp-static-site-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simbo%2Fgulp-static-site-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simbo","download_url":"https://codeload.github.com/simbo/gulp-static-site-generator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238212440,"owners_count":19434955,"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-09-24T13:38:40.402Z","updated_at":"2025-10-25T21:32:03.639Z","avatar_url":"https://github.com/simbo.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"gulp-static-site-generator\n==========================\n\n  \u003e A static site generator for gulp supporting markdown, templates, pretty URLs and more.\n\n[![npm Package Version](https://img.shields.io/npm/v/gulp-static-site-generator.svg?style=flat-square)](https://www.npmjs.com/package/gulp-static-site-generator)\n[![MIT License](http://img.shields.io/:license-mit-blue.svg?style=flat-square)](http://simbo.mit-license.org)\n[![Gitter](https://img.shields.io/gitter/room/simbo/gulp-static-site-generator.svg?style=flat-square)](https://gitter.im/simbo/gulp-static-site-generator)\n\n[![Travis Build Status](https://img.shields.io/travis/simbo/gulp-static-site-generator/master.svg?style=flat-square)](https://travis-ci.org/simbo/gulp-static-site-generator)\n[![Codecov Test Coverage](https://img.shields.io/codecov/c/github/simbo/gulp-static-site-generator.svg?style=flat-square)](https://codecov.io/github/simbo/gulp-static-site-generator)\n\n[![Dependencies Status](https://img.shields.io/david/simbo/gulp-static-site-generator.svg?style=flat-square)](https://david-dm.org/simbo/gulp-static-site-generator)\n[![devDependencies Status](https://img.shields.io/david/dev/simbo/gulp-static-site-generator.svg?style=flat-square)](https://david-dm.org/simbo/gulp-static-site-generator#info=devDependencies)\n\n---\n\n\u003c!-- MarkdownTOC --\u003e\n\n- [About](#about)\n  - [Features](#features)\n  - [Demo](#demo)\n- [Setup and usage](#setup-and-usage)\n- [Options](#options)\n  - [Defaults overview](#defaults-overview)\n  - [Options properties](#options-properties)\n- [Template Data](#template-data)\n  - [Basic site structure data](#basic-site-structure-data)\n- [License](#license)\n\n\u003c!-- /MarkdownTOC --\u003e\n\n---\n\n\n## About\n\n\n### Features\n\n  - render templates to html\n    (customizable template engine, defaults to [jade](https://github.com/pugjs/jade))\n  - render markdown to html and wrap it in a layout template\n    (customizable markdown engine, defaults to [marked](https://github.com/chjj/marked))\n  - extract frontmatter data from all markdown, template and html files\n    (using [gray-matter](https://github.com/jonschlinkert/gray-matter))\n  - provide recursively merged `options.data`,\n    *[basic site structure data](#basic-site-structure-data)*,\n    stream data and frontmatter data for template usage\n  - sanitize file and folder names and create seo-friendly/pretty urls\n    (using [slug](https://github.com/dodo/node-slug))\n  - pass-through all files that are not markdown, templates or html\n  - transform drafts only in development environment\n  - customizable options and behavior\n\n\n### Demo\n\nYou can find an example implementation in \n[./demo](https://github.com/simbo/gulp-static-site-generator/tree/master/demo)\nwithin this plugin's repository.\n\n\n## Setup and usage\n\nInstall `gulp-static-site-generator` using [npm](https://www.npmjs.com/).\n\nThis module is a [gulp](https://github.com/gulpjs/gulp) plugin.\nYou can use it in your `gulpfile.js`:\n\n``` js\nvar gulp = require('gulp'),\n    ssg = require('gulp-static-site-generator');\n\nvar options = {\n  // your custom options\n};\n\ngulp.task('ssg', function() {\n  return gulp.src('./src/site/**/*')\n    .pipe(ssg(options))\n    .pipe(gulp.dest('./dest'));\n});\n```\n\n\n## Options\n\n\n### Defaults overview\n\n``` js\n{\n  basePath: '/',\n  data: {},\n  defaultLayout: false,\n  jade: jade,\n  jadeOptions: {\n    basedir: path.join(process.cwd(), 'src')\n  },\n  layoutPath: 'layouts',\n  marked: marked,\n  markedOptions: {\n    renderer: renderer\n  },\n  prettyUrls: true,\n  regexpHtml: /\\.html$/i,\n  regexpMarkdown: /\\.(md|markdown)$/i,\n  regexpTemplate: /\\.jade$/i,\n  renderCode: renderCode,\n  renderTemplate: renderTemplate,\n  renderMarkdown: renderMarkdown,\n  slugify: true,\n  slugOptions: {\n    mode: 'rfc3986',\n    remove: /^\\./g\n  },\n\n}\n```\n\n\n### Options properties\n\n\n#### basePath\n\nType: *String*\n\nDefault: `'/'`\n\nThe base path to generate URL paths. Note that this is only for URL path \ngenerating and should not contain protocol or domain.\n\n\n#### data\n\nType: *Object*\n\nDefault: `{}`\n\nGlobal template data. See also readme section about [template data](#template-data).\n\n\n#### defaultLayout\n\nType: *String*\n\nDefault: `false`\n\nPath to default layout, relative to `options.layoutPath`. Will be used for \ntemplate data's `layout` property, which can be overridden using frontmatter.\nSee also readme section about [template data](#template-data).\n\n\n#### jade\n\nType: *Object*\n\nDefault: `require('jade')` (included dependency)\n\n*jade* module. You can set your own required *jade*, i.e. to use a specific \nversion or applying custom filters.\n\n\n#### jadeOptions\n\nType: *Object*\n\nDefault:\n``` js\n{\n  basedir: path.join(process.cwd(), 'src')\n}\n```\n\n[Options](http://jade-lang.com/api/) passed to `options.jade.compile`.\n\n\n#### layoutPath\n\nType: *String*\n\nDefault: `'layouts'`\n\nPath to layouts, relative to `process.cwd()` or absolute.\n\n\n#### marked\n\nType: *Function*\n\nDefault: `require('marked')`\n\n*marked* module. You can set your own required marked to use a specific version.\n\n\n#### markedOptions\n\nType: *Object*\n\nDefault: \n``` js\n{\n  renderer: renderer // marked renderer with customized code highlighting\n}\n```\n\n[Options](https://github.com/chjj/marked#options-1) passed to `options.marked.setOptions`.\n\n\n#### passThrough\n\nType: *Boolean*\n\nDefault: `true`\n\nIf set to `true`, all files, which are not recognized as markdown, templates or \nHTML, will be passed-through untransformed.\n\n\n#### prettyUrls\n\nType: *Boolean*\n\nDefault: `true`\n\nIf set to `true`, all URL paths will be transformed to seo-friendly or so called\n\"pretty\" URLs (for example, `/foo.html` will be transformed to \n`/foo/index.html`).\n\nIf a file would generate an URL path, that is already owned by another file in \nbuffer, output of this file is skipped and a warning is displayed in console log.\n\n\n#### regexpHtml\n\nType: *RegExp*\n\nDefault: `/\\.html$/i`\n\nA regular expression to recognize a file as HTML by testing its relative file path.\n\n\n#### regexpMarkdown\n\nType: *RegExp*\n\nDefault: `/\\.(md|markdown))$/i`\n\nA regular expression to recognize a file as Markdown by testing its relative file path.\n\n\n#### regexpTemplate\n\nType: *RegExp*\n\nDefault: `/\\.jade$/i`\n\nA regular expression to recognize a file as Template by testing its relative file path.\n\n\n#### renderCode\n\nType: *Function*\n\nDefault: `renderCode` ([see source](https://github.com/simbo/gulp-static-site-generator/blob/master/index.js))\n\nA function to render and highlight the string contents of a markdown sourcecode \nblock. The default function uses [highlight.js](https://github.com/isagalaev/highlight.js)\nfor syntax highlighting. It accepts the two string parameters `code` and `lang` \nand should return a string containing HTML. \n\nThe function is used as code renderer for the *marked* renderer referenced at \n`options.markedOptions.renderer`.\n\n\n#### renderTemplate\n\nType: *Function*\n\nDefault: `renderTemplate` ([see source](https://github.com/simbo/gulp-static-site-generator/blob/master/index.js))\n\nA function to render a template string to HTML, using *jade* by default. It \naccepts three parameters: a template `contents` string to render, an optional \nobject with template `data` and an optional absolute `filepath` string to \ncorrectly include or extend other template files. It should return a string \ncontaining HTML.\n\nWhen setting a custom template rendering function, the options `jade` and \n`jadeOptions` won't have any effect.\n\n\n#### renderMarkdown\n\nType: *Function*\n\nDefault: `renderMarkdown` ([see source](https://github.com/simbo/gulp-static-site-generator/blob/master/index.js))\n\nA function to render markdown to HTML, using *marked* by default. It accepts a \nmarkdown `contents` string as the only argument and should return a string \ncontaining HTML.\n\nBeside being used to render markdown files, this function is also referenced as \n`options.jade.filters.markdown` to render markdown blocks or includes in *jade* \ntemplates.\n\nWhen setting a custom markdown rendering function, the options `marked`, \n`markedOptions` and `renderCode` won't have any effect.\n\n\n#### slugify\n\nType: *Boolean*\n\nDefault: `true`\n\nIf set to `true`, folder and file names within the generated URL path of a file\nwill be sanitized by *slug*.\n\n\n#### slugOptions\n\nType: *Object*\n\nDefault:\n``` js\n{\n  mode: 'rfc3986',\n  remove: /^\\./g\n}\n```\n\n[Options](https://github.com/dodo/node-slug#options) passed to *slug*.\n\n\n## Template Data\n\nTemplate data will be passed to `options.renderTemplate` to set template\nvariables when rendering.\n\nThe template data for a file results from an recursive merge of `options.data`,\n*basic site structure data*, the respective file stream's `data` property and \nthe data extracted from the file's frontmatter using *gray-matter*.\n\n### Basic site structure data\n\nThe *basic site structure data* for each file is automatically generated during\ntransformation and can be overridden by applying data to the respective stream \nor setting frontmatter in the file contents. \n\nBy overriding `data.relativePath`, you can manipulate the files output URL path,\nwhich would otherwise be generated from the source file's relative path.\n\nAssuming the source file `foo.jade` was globbed with `gulp.src('./src/**.*')`\nwith `/bar` as current working directory, the *basic site structure data* of \nthis file using default options without overrides would look like this:\n\n``` js\n{\n  basePath: '/',                  // url base path from options.basePath\n  relativePath: 'foo/index.html', // relative url path from base path\n  path: '/foo/index.html',        // full url path to file\n  urlPath: '/foo/',               // prettified URL path (depending on `options.prettyUrls`)\n  srcBasePath: '/bar/src/',       // absolute path to source base dir\n  srcRelativePath: 'foo.jade',    // relative path to source file from source base dir\n  srcPath: '/bar/src/foo.jade',   // absolute path to source file\n  contents: '',                   // contents to use in a layout template\n  draft: false,                   // is this a draft?\n  layout: false                   // path to layout template, relative to `options.layoutPath`\n}\n```\n\n\n## License\n\n[MIT \u0026copy; 2016 Simon Lepel](http://simbo.mit-license.org/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimbo%2Fgulp-static-site-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimbo%2Fgulp-static-site-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimbo%2Fgulp-static-site-generator/lists"}