{"id":14975423,"url":"https://github.com/jquery/grunt-jquery-content","last_synced_at":"2025-04-16T01:09:21.300Z","repository":{"id":3635289,"uuid":"4702006","full_name":"jquery/grunt-jquery-content","owner":"jquery","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-14T17:01:53.000Z","size":331,"stargazers_count":40,"open_issues_count":7,"forks_count":32,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-04-16T01:08:46.020Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"XSLT","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jquery.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","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,"zenodo":null}},"created_at":"2012-06-18T14:42:47.000Z","updated_at":"2025-04-14T17:01:54.000Z","dependencies_parsed_at":"2023-11-12T17:48:22.838Z","dependency_job_id":"b0e853fa-7506-4d5d-8c97-cb8119f27753","html_url":"https://github.com/jquery/grunt-jquery-content","commit_stats":{"total_commits":259,"total_committers":23,"mean_commits":11.26086956521739,"dds":0.4054054054054054,"last_synced_commit":"1abaf4b81c800f332880583e6d97b0ef6b2b44c0"},"previous_names":[],"tags_count":73,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jquery%2Fgrunt-jquery-content","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jquery%2Fgrunt-jquery-content/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jquery%2Fgrunt-jquery-content/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jquery%2Fgrunt-jquery-content/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jquery","download_url":"https://codeload.github.com/jquery/grunt-jquery-content/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249178212,"owners_count":21225349,"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:52:00.750Z","updated_at":"2025-04-16T01:09:21.276Z","avatar_url":"https://github.com/jquery.png","language":"XSLT","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Tested with QUnit](https://img.shields.io/badge/tested_with-qunit-9c3493.svg)](https://qunitjs.com/)\n\n# grunt-jquery-content\n\nA collection of Grunt tasks for deploying jQuery documentation sites.\n\nThis module builds on top of [node-wordpress](https://github.com/scottgonzalez/node-wordpress) and the [Gilded WordPress](https://github.com/scottgonzalez/gilded-wordpress) plugin. See the Gilded WordPress documentation for details on the [directory structure and file formats](https://github.com/scottgonzalez/gilded-wordpress#directory-structure).\n\n## Getting started\n\nPrerequisites:\n\n* Install the gilded-wordpress.php plugin on your WordPress site (copy from [Gilded WordPress](https://github.com/scottgonzalez/gilded-wordpress)).\n* Depending on what kind of files you want to upload as \"resources\", you may need to configure WordPress to allow more permissive uploads. See the [Gilded WordPress documentation](https://github.com/scottgonzalez/gilded-wordpress#permissive-uploads) for how to do this.\n\nBasic set up for your project:\n\n1. add `wordpress` configuration to Gruntfile.js.\n2. add `build-posts` task configuration to Gruntfile.js.\n3. add `grunt.registerTask( \"build\", [ \"build-posts\" ] );` to Gruntfile.js\n\nYou can now use `grunt wordpress-deploy` to build and deploy your project.\n\nThe `wordpress-deploy` task is a tree of the following tasks:\n\n* `wordpress-deploy`\n  * `build-wordpress`\n    * `check-modules`\n    * `lint` (empty placeholder by default)\n    * `clean-dist`\n    * `build` (undefined by default)\n  * `wordpress-publish`\n    * `wordpress-validate`\n    * `wordpress-sync`\n\nThe following optional tasks are made available to use via the `lint` or `build` phase:\n\n* lint:\n  *  `xmllint`\n* build:\n  * `build-posts`\n  * `build-resources`\n  * `build-xml-entries`\n  * `build-xml-categories`\n  * `build-xml-full`\n\n## Config\n\n```javascript\ngrunt.initConfig({\n\twordpress: {\n\t\turl: \"wordpress.localhost\",\n\t\tusername: \"admin\",\n\t\tpassword: \"admin\",\n\t\tdir: \"dist\"\n\t}\n});\n```\n\n* `url`: The URL for the WordPress install.\n  Can be a full URL, e.g., `http://wordpress.localhost:1234/some/path`\n  or as short as just the host name.\n  If the protocol is `https`, then a secure connection will be used.\n* `host` (optional): The actual host to connect to if different from the URL, e.g., when deploying to a local server behind a firewall.\n* `username`: WordPress username.\n* `password`: WordPress password.\n* `dir`: Directory containing posts, taxonomies, and resources.\n  * See the [Gilded WordPress documentation](https://github.com/scottgonzalez/gilded-wordpress#directory-structure) for details on the directory structure and file formats.\n\n## Tasks\n\n### clean-dist\n\nThis task removes all files in the `dist/` directory.\n\n### lint\n\nThis is an empty task list by default. If the site contains any lint checks, they should be defined here. For example, API documentation sites should have the following task list:\n\n```javascript\ngrunt.registerTask( \"lint\", [ \"xmllint\" ] );\n```\n\n### build-posts\n\n```javascript\ngrunt.initConfig({\n\t\"build-posts\": {\n\t\tpage: \"pages/**\"\n\t},\n});\n```\n\nThis multi-task takes a list of html or markdown files, copies them to `[wordpress.dir]/posts/[post-type]/`, processes `@partial` entries and highlights the syntax in each. The keys are the post types for each set of posts.\n\nSee the [`postPreprocessors` export](#postpreprocessors) for a hook to implement custom processing.\n\n### build-resources\n\nThis mult-task copies all source files into `[wordpress.dir]/resources/`.\n\n```javascript\ngrunt.initConfig({\n\t\"build-resources\": {\n\t\tall: \"resources/**\"\n\t},\n});\n```\n\n### xmllint\n\nThis multi-task lints XML files to ensure the files are valid.\n\n### build-xml-entries\n\nThis multi-task generates HTML files to be published to WordPress by parsing the source XML files and transforming them through `entries2html.xsl`. The generate files are copied to `[wordpress.dir]/posts/post/`.\n\nThe content repo must create its own `entries2html.xsl` file which must import `node_modules/grunt-jquery-content/tasks/jquery-xml/entries2html-base.xsl`.\n\n### build-xml-categories\n\nThis task reads `categories.xml` from the root of the content repo and generates `[wordpress.dir]/taxonomies.json`.\n\n`categories.xml` should have the following format:\n\n```xml\n\u003ccategories\u003e\n\t\u003ccategory name=\"Category 1\" slug=\"category1\"\u003e\n\t\t\u003cdesc\u003eA description of the category.\u003c/desc\u003e\n\t\t\u003ccategory name=\"Subcategory\" slug=\"subcategory\"\u003e\n\t\t\t\u003cdesc\u003e\u003c![CDATA[A description containing \u003cem\u003eHTML\u003c/em\u003e!]]\u003e\u003c/desc\u003e\n\t\t\u003c/category\u003e\n\t\u003ccategory name=\"Another Category\" slug=\"another-category\"\u003e\n\t\t\u003cdesc\u003eThis category is boring.\u003c/desc\u003e\n\t\u003c/category\u003e\n\u003c/categories\u003e\n```\n\nCode examples in the descriptions will be syntax highlighted.\n\n### build-xml-full\n\nThis task generates a single XML file that contains all entries and stores the result in `[wordpress.dir]/resources/api.xml`.\n\n### wordpress-validate\n\nWalks through the `wordpress.dir` directory and performs various validations, such as:\n\n* Verifying that XML-RPC is enabled for the WordPress site.\n* Verifying that the custom XML-RPC methods for gilded-wordpress are installed.\n* Verifying the taxonomies and terms in `taxonomies.json`.\n* Verifying that child-parent relationships for posts are valid.\n* Verifying data for each post.\n\n### wordpress-sync\n\nSynchronizes everything in `wordpress.dir` to the WordPress site.\nThis will create/edit/delete terms, posts, and resources.\n\n*Note: `wordpress-validate` must run prior to `wordpress-sync`.*\n\n### wordpress-publish\n\nAlias task for `wordpress-validate` and `wordpress-sync`.\nThis is useful if your original source content is already in the proper format,\nor if you want to manually verify generated content between your custom build and publishing.\n\n### wordpress-deploy\n\nAlias task for `build-wordpress` and `wordpress-publish`.\nThis is useful if you are generating content for use with `wordpress-sync`.\nSimply create a `build-wordpress` task that populates the `wordpress.dir` directory\nand your deployments will be as simple as `grunt wordpress-deploy`.\n\n### deploy\n\nAlias task for `wordpress-deploy`.\n\nSince most projects that use grunt-jquery-content have one deploy target (WordPress),\nthere is a built-in `deploy` task that just runs `wordpress-deploy`.\n\nIf your project has other deploy targets, you can redefine `deploy` as an alias that runs both `wordpress-deploy` and your other deployment-related tasks.\n\n## Page content\n\nThe following features are available in pages built via the `build-posts` task.\n\n### Markdown\n\nUsing markdown files provides additional features over HTML files. By default, links for each header are automatically generated for markdown files.\n\nIn addition to the [standard metadata](https://github.com/scottgonzalez/gilded-wordpress#post-files) for post files, the following properties can be set:\n\n* `noHeadingLinks`: When set to `false`, heading links won't be generated.\n* `toc`: When set to `true`, a table of contents will be inserted at the top of the post based on the headings within the post.\n\n### `@partial`\n\nUsage:\n\n```html\n\u003cpre\u003e\u003ccode data-linenum\u003e@partial(resources/code-sample.html)\u003c/code\u003e\u003c/pre\u003e\n```\n\nWhere `resources/code-sample.html` is a relative path in the current directory. That html file will be inserted, escaped and highlighted.\n\n### `@placeholder`\n\nInside markup included with `@partial`, you can mark sections of code as `@placeholder` code, to be excluded from the inserted code, replaced with an html comment.\n\nUsage:\n\n```html\nregular markup will show up here\n\u003c!-- @placeholder-start(more markup) --\u003e\nthis will be replaced\n\u003c!-- @placeholder-end --\u003e\nother content\n```\n\nThat will result in:\n\n```html\nregular markup will show up here\n\u003c!-- more markup --\u003e\nother content\n```\n\n## Exports\n\nThe grunt-jquery-content module primarily registers Grunt tasks, but it also exports some methods through the `require()` API.\n\n### `syntaxHighlight( content )`\n\nSyntax highlights content.\n\n* `content` String: The string the highlight.\n\n### `postPreprocessors`\n\nHooks for modifying the posts before they're processed in the [`build-posts`](#build-posts) task.\n\n`postPreprocessors` is a hash of preprocessors, where the key is the post type and the value is a function which modifies the post.\n\nThe functions must be in the form of:\n`function( post, fileName, callback )`\n\n* `post` Object: The post being processed.\n* `fileName` String: The name of the file used to generate the post object.\n* `callback` function( error, post ): Callback to invoke after modifying the post.\n  * `error`: An `Error` instance, if there was an error while modifying the post.\n  * `post` The modified post.\n\nBy default, posts are placed in the `[wordpress.dir]/[post-type]` directory using the same relative path and file name as the source file. The relative path can be changed by setting the `fileName` property on the post.\n\nIf a preprocessor is not defined for the given post type, then the `_default` preprocessor will be used.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjquery%2Fgrunt-jquery-content","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjquery%2Fgrunt-jquery-content","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjquery%2Fgrunt-jquery-content/lists"}