angular / material.angular.io

Docs site for Angular Components

Angular Components Docs Site

This is the repository for the Angular Components documentation site.

Versions of this site are also available for

• v5
• v6
• v7
• v8
• v9
• v10
• v11
• v12

Contributing

Please open bugs against the Angular Material and CDK components, directives, documentation contents, API docs, and demos in the Angular Components repo.

Please only open issues with the documentation site itself (not the content) in this repo. This includes issues like the navigation not working properly, examples or documentation not being presented in an accessible way, issues with rendering or layout of the documentation pages, etc.

Where does the content come from?

The guides, examples, and docs content repo angular/material2-docs-content contains the documentation content and examples. They are generated from:

• Angular Material and CDK Guides
• Material components, services, and directives
• CDK components, services, and directives

Development Setup

1. Make sure you have NodeJS LTS installed
2. Make sure you have Yarn installed
3. Install the project's dependencies
   • yarn install
4. Update to the latest version of the docs-content and examples
   • yarn build:content

Development Server

1. Run yarn start for a dev server. Navigate to http://localhost:4200/.

Build

Run yarn prod-build to build the project.

Running unit tests

1. Run yarn test to execute the unit tests via Karma.

Running end-to-end tests

Run yarn e2e to execute the end-to-end tests via Protractor. Before running the tests make sure you are serving the app via yarn start.

Deployment instructions

> yarn install
> yarn upgrade @angular/components-examples

# Development
> yarn publish-dev

# Production
> yarn publish-prod

material.angular.io's Issues

Implement ApiViewer component

This will consume the json generated from TypeDoc and output tabular API docs.

• First step will be a service that takes in the TypeDoc output and gives back a data structure that's more in-line with what we're interested in.
• Needs to be themable based on current material theme

Needs design from #3

Add server-side prerendering

• When dealing with multiple versions of docs, we likely only want to support prerendering the latest/ version.
• Will likely be implemented with firebase dynamic hosting

Implement user preferences service

We should store the following via a user preferences service and keep those preferences in localStorage

• The selected theme
• Preferred external example viewer (Plunker, CodePen, Jsbin, etc.) (future enhancement)

This is a lower priority than main app content.

Tooling to generate API docs from material2 source

Design badge for "Experimental" API

Certain API / components will be marked as "Experimental". It should be very prominent in that component's page.

This is a low priority item for the rest of this year.

Dialog example should include code from dialog-result-example-dialog.html

The overview for the Dialog talks about using elements such as <md-dialog-content> and <md-dialog-actions>. However, no examples of actual code using these elements is visible, because that code would be in the dialog-result-example-dialog.html file (referenced in the .ts files in both the overview and the example), but the actual content of that html file is not visible anywhere.

feat: add a new "file an issue" button in components page

When a user is working with a component and spots a bug, they're probably having https://material.angular.io/components/component/{someComponent} open in their browser. Why not to add a direct github link for submitting a new issue for that component.
I can craft a PR if you think it's a good idea.

Implement Document Viewer component

This is a component that loads a static HTML document (generated from markdown) into itself, and then dynamically loads components into that static document based on certain placeholders.

The most common placeholder will be for a live example. API docs may also be loaded this way.

Plunker fails to open in Chrome 56

Form is not attached to the document and receiving new error: "Form submission canceled because the form is not connected"

See https://chromium.googlesource.com/chromium/src/+/962c2a22ddc474255c776aefc7abeba00edc7470%5E!/ for the chromium change

Examples should show all source files

Right now the example-viewer is hard-coded to show one of each html/css/ts file. This should show all of the files used for the examples.

The should follow a tooling update that changes the example manifest to be automatically generated instead of maintained by hand (#174)

Design light/dark theme toggle

Need to be able to toggle between light and dark theme, similar to https://material2-app.firebaseapp.com/

Remove route redundancy for component page

The current route is

https://material.angular.io/components/component/checkbox

It instead should be

https://material.angular.io/components/checkbox

We can add a firebase rewrite rule to avoid breaking old links when we make the change.

Design API docs UX

This will cover the type of information under "API" on the material docs site.

One "API docs" page may contain one or more classes with descriptions for each class, method, and property (potentially plus types as well).

Components may additionally have parts of their API docs for @Inputs and @Outputs (we might just call theme properties and events)

(material1 version of this)

Implement theme switcher

We're going to shamelessly steal the picker from https://fonts.google.com/

This is lower priority than the main docs content

Run unit and e2e tests on travis

Use mdTabNav for component-viewer instead of tab-group

Switching between Overview, API, and Examples should be captured in the route.

Add table-of-contents for jump navigation on docs

Similar to the right-hand-side of https://developers.google.com/web/fundamentals/getting-started/principles/

Implement main application layout and navigation

Assets are on slack channel.

No mixin named md-core

ERROR in ./src/main.scss
Module build failed: ModuleBuildError: Module build failed:
undefined
        ^
      No mixin named md-core

Scroll down does not work on Safari.

https://material.angular.io/components
In context section next to left navigation bar, the scroll does not work on Safari.

The console shows this message only on Safari.
Failed to load resource: the server responded with a status of 404 (HTTP/2.0 404) https://ajax.googleapis.com/ajax/libs/hammerjs/2.0.8/hammer.min.js.map

Snackbar plunker example does not work

Go to plunker from this example: https://material.angular.io/components/component/snack-bar

See error:
EXCEPTION: Error in snack-bar-component-example.html:0:0 caused by: No component factory found for PizzaPartyComponent. Did you add it to @NgModule.entryComponents?

Either Responsiveness not yet implemented or might not be documented.

How to manage the responsiveness in grid system.

Some docs site styles are bleeding into examples

See the weird border around the tables in the input example:

https://material.angular.io/components/component/input

No link to Github repository?

On the current https://material.angular.io/ I haven't found a link to the Github repo. If I overlooked it, maybe it's too small or hidden?

A11y Screen Reader - Page structure challenges

Screen reader WCAG issues.

1. Perceivable: Page structure lacks content relationships; (no region), (missing text label on ), (missing text label on ).
2. Operable: Pressing Enter key on Link elements (like "COMPONENTS" and "GUIDES") provide no verbal feedback of cursor focus change to notify the blind user.
3. Understandable: The page is simple but is missing Breadcrumb and proper page Title for orientation.
4. Robust: Not tested.

Angular Material Accessibility Introduction.mp4: https://www.dropbox.com/s/rz2gtuhnbx9czus/Angular%20Material%20Accessibility%20Introduction.mp4?dl=0

Duplicate properties in API docs

This is an example taken from the API references tab of the Select Component.

Design Search

Not a top priority, but we will need to have an in-site search eventually. My current thinking is to add it to the top nav. Probably includes an autocomplete.

Also need to think about how to to show the results.

Bug: Wrong initial focus-overlay on a button in the sidenav

I have a sidenav with some md-button navigation buttons in it. By default, my navigation is closed.

The problem is when I trigger to show the navigation for the first time and hover somewhere on the sidenav it makes the first button with focus-overlay effect. Then when I hover on some of the other buttons the hover effect is still there for the first button. I have to click somewhere on the screen to remove the wrong effect.

Link with example of the bug: https://plnkr.co/edit/pNv9Bx4o1qQSF2bpOqyM?p=preview

Implement component view

Page for a single component.

Should use md-tab-nav-bar to go between "Overview", "API", and "Examples"

@tinayuangao we need to confirm the design before getting started on this

Example-viewer component no longer works

In th edemo app, the example-viewer component is always empty.

Optimize image assets as part of publish

Likely pngcrush and svgo

Add links for additional help/support resources

The docs site could use a page helping users find outlets to the community and where they can ask questions or provide support for others looking for help.

• Google Groups
• StackOverflow
• Gitter

'md-sidenav-layout' used in page 'component-sidenav' and cause page load error

According to the sidenav README should use md-sidenav-container instead.

NOTE: The md-sidenav-layout element is deprecated. md-sidenav-container should be used instead.

Unable to open samples

When opening https://material.angular.io/guide/leashed-in an exception is created. Same exception encountered with the material2-app sample as well.

TypeError: Cannot read property 'document' of undefined

OS: WINDOWS 10 Pro
Browser: Chrome v56.0.2924.87

Swiping slider doesn't work

As mentioned in angular/components#3394 the swipe gesture doesn't seem to be working on md-slider on the docs site (https://material.angular.io/components/component/slider) in firefox. It does however work in the plunker link on the same example, so seems like something on the docs site is interfering.

Tooling to generate static html from markdown docs

Sample App Example on Getting Started Page

I was just going through the Angular Material documentation at https://material.angular.io I noticed on Getting Started page there were few App Demo Links given at the end of the page. On clicking either of the links on Getting Started page for app demo these links redirect the user back to https://material.angular.io without showing any data and disabling all the links. Let me explain with the help of screenshots.

1. Click on either of the links below. Through this screenshot I wanted to show that when we hover on the first link i.e. Material Sample App, it is not like that we are clicking on some wrong link checkout second screenshot in this step only
   
   
2. It starts showing something like this
   
3. Now if you try to click on any of the links given in the navbar, it does not perform any of the action. It keeps on showing the page as shown in step 2
4. If you press F5 i.e. reload that page without making any changes in the address we were redirected to it shows the starting page as shown
   

Similarly, there is an issue with the second sample app link.

Reset scroll when switching between components

Bug, feature request, or proposal:

I propose reset the scroll position to the top when switching between components on the docs.

What is the expected behavior?

What is the current behavior?

It stays where you are. ie go to autocomplete scroll half way down then go to input and you are halfway down that page when you probably want to be at the top.

What are the steps to reproduce?

Providing a Plunker (or similar) is the best way to get the team to see your issue.
Plunker template: https://goo.gl/DlHd6U

https://material.angular.io/components/component/select

What is the use-case or motivation for changing an existing behavior?

Usability

The selector did not match any elements

The Dialog Component in the plunker Demo throws exeption: "The selector "dialog-overview-example-dialog" did not match any elements".

Sample Angular Material projects link breaks site

When I go to https://material.angular.io/guide/getting-started and follow the links at the bottom of the page i get

Loading document...

and console errors.

TypeError: Cannot read property 'document' of undefined

and nothing else happens and to be able to continue to use the site I had to refresh the page.

Material Sample App
https://material.angular.io/guide/material2-app

Angular Connect 2016 Demo
https://material.angular.io/guide/leashed-in

EDIT: seems to be same as #105

Broken link to theming on getting started page

https://github.com/angular/material.angular.io/blob/master/src/assets/documents/guides/getting-started.html#L25

<a href="guides/theming.md">theming guide</a>

should be

<a href="/guide/theming">theming guide</a>

Also on the same line, what's the relevance of :trident:? If it's meant to be replaced with emoji, it's not working, instead renders as:

Add marker for "Experimental" APIs

See #25

Implement LiveExampleViewer

• Dynamically loads a live-example component as the default view.
• Can expand to show the source (ts, html, css) with syntax highlighting
• Can open on Plunker
• Themable (including the syntax highlighting) based on current material theme.

Design tracked in #2

Create PR labels matching material2 repo

Reference Error in material.angular.io/src/app/examples/card-fancy/card-fancy-example.css

There is error in referencing the file in
material.angular.io/src/app/examples/card-fancy/card-fancy-example.css for background image of header.
the given reference is 'assets/img/examples/shiba1.jpg' which is giving error on window, it should be '/assets/img/examples/shiba1.jpg'

Design "Live Example" component

This should cover the features that are available in the material docs site:

• Live example
• Can expand source in-page
• Can link out to Plunker

It would also be good to add an LTR/RTL toggle for the examples as well, but that may come later in the implementation.

Site is down

https://material.angular.io/ seems to be down, or something is wrong with the ssl credentials.

I cannot scroll docs' main content in safari

When I open any doc page, I cannot scroll right zone with content, I can scroll only left zone (with components list).

Env: macOS Sierra 10.12.2, Safari 10.0.2 (12602.3.12.0.1)

UPD. In Firefox left column (with menu list) and right column (with content) scrolls together (must scrolls separately instead).

Support multiple versions of documentation

Add Google Analytics tag