{"id":28577308,"url":"https://github.com/material-components/material-components-site-generator","last_synced_at":"2025-06-11T00:37:28.160Z","repository":{"id":53708293,"uuid":"85105157","full_name":"material-components/material-components-site-generator","owner":"material-components","description":"Generator of Material Components documentation sites.","archived":false,"fork":false,"pushed_at":"2024-03-12T17:44:21.000Z","size":3625,"stargazers_count":75,"open_issues_count":16,"forks_count":44,"subscribers_count":24,"default_branch":"master","last_synced_at":"2024-03-25T20:23:58.750Z","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":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/material-components.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":"2017-03-15T18:05:22.000Z","updated_at":"2024-01-25T15:59:10.000Z","dependencies_parsed_at":"2022-09-02T04:20:51.012Z","dependency_job_id":null,"html_url":"https://github.com/material-components/material-components-site-generator","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/material-components%2Fmaterial-components-site-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/material-components%2Fmaterial-components-site-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/material-components%2Fmaterial-components-site-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/material-components%2Fmaterial-components-site-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/material-components","download_url":"https://codeload.github.com/material-components/material-components-site-generator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/material-components%2Fmaterial-components-site-generator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259177063,"owners_count":22817308,"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-06-11T00:37:17.580Z","updated_at":"2025-06-11T00:37:28.145Z","avatar_url":"https://github.com/material-components.png","language":"JavaScript","readme":"# Material Components Docsite Generator\n\nThe docsite generator transforms Markdown files found in material-component repos, styles them,\nmoves them around, rewrites links to match, and spits out\n[https://material.io/components](https://material.io/components).\n\n## Prerequisites\n\n- Ruby\n  - Using OS X's system Ruby is not recommended, because requires writing to\n    system folders. [rbenv](https://github.com/rbenv/rbenv) is a better option.\n    The required Ruby version is indicated in the Gemfile.\n- Xcode Command Line Tools (if on a mac)\n- Homebrew\n- Node.js v7+\n\n## Installation\n\n```sh\ngem install bundler\nbundle install\nbrew update\nbrew install yarn\nyarn install\n```\n\n## Building the Site\n\nThe build script works with one or more component/documentation repos as input.\nA documentation repo must have an `.mdc-docsite.yml` file in its root, and it should\ndefine a [basepath](#basepath) variable at the very least.\n\nRunning\n\n```sh\n$ scripts/build path/to/mdc/repo_1 [path/to/mdc/repo_2 ...]\n```\n\nwill output a static site in the `dist/` directory. In order to test the site,\nrun a local web server with the `dist/` directory as its root.\n\n### Change Watching\n\nDuring development, it can be useful to have site builds triggered by changes to\nfiles. I've included very basic file watching functionality (not everything is\nwatched) that can be enabled with the `--watch` option.\n\n### Build Environments\n\nBy default, `scripts/build` will build the site using a development\nconfiguration, which outputs source maps and tidied HTML.\n\nProduction builds should have `BUILD_ENV=production` precede the command to\nbuild optimized code.\n\n### Production site build (single platform)\n\nIf you're looking to build the site for a single platform, run the following:\n\n```sh\nBUILD_ENV=production scripts/build --apidocs /path/to/mdc/repo/root\n```\n\n### Production site build (all platforms)\n\nAn incredibly slow and naive script has been written that performs a complete\nbuild of the site. It will clone the four repos into a folder called `docs-src`,\nand write the final output to `dist/`.\n\n```sh\nscripts/prod_build\n```\n\n## Writing Documentation\n\nThe following describes how to write documentation for the\n[material.io/components](https://material.io/components) site.\n\n### Adding Configuration Metadata\n\nOnly markdown files containing [Front Matter](https://jekyllrb.com/docs/frontmatter/)\nconfiguration metadata will be transformed into HTML by the site generation tool.\n\nThe configuration *must appear at the top of the file*, and be delimited with `\u003c!--docs:` and\n`--\u003e`. Example:\n\n```markdown\n\u003c!--docs:\ntitle: \"Page Title\"\n--\u003e\nPlain old Markdown\n```\n\n##### Sample Config – Component\n\nBelow is a sample metadata block taken from a component's README.md. Take notice of the casing and\npluralization used for each field. [The fields are described](#configuration-fields) in more detail\nbelow.\n\n```\n\u003c!--docs:\ntitle: \"Buttons\" # name of component (not class), plural, title case\nexcerpt: \"Material Design-styled buttons.\"\nlayout: detail # do not change\nsection: components # do not change\nicon_id: text_field # described below\npath: /catalog/text-fields/ # child of /catalog/, kebab-case, plural\n--\u003e\n```\n\n##### Sample Config – General Documentation (non-component)\n\n```\n\u003c!--docs:\ntitle: \"How to Write Components\"\nexcerpt: \"A tutorial on how to write components.\"\nlayout: landing # do not change\nsection: docs # do not change\npath: /docs/how-to-write-components/ # child of /docs/, kebab-case\n--\u003e\n```\n\n#### Configuration Fields\n\n##### title\n\n`title` is used as link text for the page in side navigation, as well as to populate the page's\n`\u003ctitle\u003e` element.\n\nFor component pages, this should be the name of the component (not the class), title-cased, and\npluralized (where appropriate).\n\n##### excerpt\n\n`excerpt` is a short (one sentence) description of the page.\n\nOn component pages, it is used as the little snippet of text diplayed in the\n[component listing](https://material.io/components/web/catalog/).\n\nIt is used on all pages to populate `\u003cmeta name=\"description\"\u003e` elements.\n\n##### section\n\nUsed to generate navigation. Should be `components` for component pages or `docs` otherwise.\n\n##### layout\n\nDetermine the Jekyll layout to use. The available layouts can be found in\n[this directory](https://github.com/material-components/material-components-site-generator/tree/master/jekyll-site-src/_layouts).\n\nComponent pages should use the `detail` layout. Documentation pages should use the `landing` layout.\n\n##### icon_id\n\nThis is only applicable to files with [`section: component`](#section).\n\nThe ID of the icon associated with a component's readme. This is displayed on component and\n[component listing](https://material.io/components/web/catalog/) pages.\n\nAn icon ID is the name of an\n[SVG in this directory](https://github.com/material-components/material-components-site-generator/tree/master/jekyll-site-src/images/component_icons),\nwithout its extension. For example, to use `bottom_navigation.svg`, your metadata should read\n`icon_id: bottom_navigation`.\n\n##### path\n\nThe destination path for the document's generated HTML.\n\nEnding the path in a `/` will write out an `index.html`.\n\nAll links to other Markdown/files will be automatically rewritten to reflect their\npaths in the generated site.\n\nConfused? Here's the rule: Write all your links so they'll work on GitHub. The site generator \nwill do the rest.\n\n##### api_doc_root\n\n`true` if the site's documentation generator should be invoked on this directory. Currently this is\nonly used on the iOS platform.\n\nIf omitted, this field defaults to `false`.\n\n##### virtual_source_path\n\nGitHub markdown files will sometimes link to a directory in the source tree that does not have an\nassociated README, or its README is inappropriate for inclusion on the documentation site.\n`virtual_source_path` exists so that you can tell a the site generator to treat a file as if it\nexists somewhere in the source repo that it doesn't, so that other files can link to it in the generated site.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaterial-components%2Fmaterial-components-site-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaterial-components%2Fmaterial-components-site-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaterial-components%2Fmaterial-components-site-generator/lists"}