docs(aio): image sweep #16609

petebacondarwin · 2017-05-06T15:20:32Z

All the images in the guides have been checked and tidied up.
Fixes #16396

@wardbell : The following should become part of the "Authors Styleguide":

Using Images

It is best to use HTML to declare images in the docs. Do not use the markdown ![...](...)
shorthand.
The HTML to use is an <img src="..." alt="..."> tag. You must supply a src attribute that is relative to the base path; and you should provide an alt attribute describing the image for accessibility. Note that Image tags do not have a closing tag.

Image Size

The doc generation process will read the image dimensions and automatically add width and
height attributes to the img tag. If you want to control the size of the image then you should
supply your own width and height images.

Images should not be wider than 700px otherwise they may overflow the width of the document
in certain viewports. If you wish to have a larger image then provide a link to the actual image that
the user can click on to see the larger images separately.

Image Formatting

There are three types of images that you can put in docs: inline, floating and standalone.

Inline Images

To create an inline image simply place the img tag in the content where you want the image to appear. E.g.

The image here <img src="..." alt="..."> is visible inline in the text.

Floating images

You can cause an image to float to the left or right of the text by applying the class="left" or class="right" attributes respectively. E.g.

<img src="..." alt="..." class="left">
This text will wrap around the to the right of this floating image.

All headings and code-examples will automatically clear a floating image.
If you need to force a piece of text to clear a floating image then you can use the following snippet:

<br class="clear">

Finally, if you have floating images inside alerts or sub-sections then it is a good idea to apply the clear-fix class to the div to ensure that the image doesn't overflow its container. E.g.

<div class="l-sub-section clear-fix">

  <img class="right" src="..." alt="...">
  Some **markdown** formatted text.

</div>

Standalone images

Some images should stand alone from the text. You do this by wrapping the img tag in a figure
tag. This causes the image to get additional styling, such as a rounded border and shadow. The text will not flow around this image but will stop before the image and start again afterword. E.g.

Some paragraph preceding the image.

<figure>
  <img src="" alt="">
</figure>

(In the future we may also support styling for adding a caption to a standalone image.)

mary-poppins · 2017-05-06T15:35:54Z

The angular.io preview for c13cd25 is available here.

mary-poppins · 2017-05-06T17:05:23Z

The angular.io preview for 8294ad3 is available here.

mary-poppins · 2017-05-06T19:02:17Z

The angular.io preview for 025c329 is available here.

mary-poppins · 2017-05-07T15:20:10Z

The angular.io preview for 9475ec7 is available here.

mary-poppins · 2017-05-07T18:07:07Z

The angular.io preview for 383ad5e is available here.

mary-poppins · 2017-05-08T09:38:43Z

The angular.io preview for ff25d22 is available here.

mary-poppins · 2017-05-08T22:37:54Z

The angular.io preview for f487edb is available here.

petebacondarwin · 2017-05-09T09:24:45Z

aio/src/styles/2-modules/_images.scss

-    float: none !important;
-  }
-}
+.content {


We only want this formatting of images within the content of documents, not the aio-shell in general.

petebacondarwin · 2017-05-09T09:25:39Z

aio/src/styles/2-modules/_images.scss

+    @media (max-width: 1300px) {
+      max-width: 100%;
+      height: auto;
+    }


If the screen is wider than 1300px then we want to use the width and height values provided in the HTML to ensure that the page is laid out correctly while the images are still loading.

But then as the screen narrows the images will be constrained by the max-width rule, which means that we need to switch to using height: auto to ensure that the proportions of the image do not change.

mary-poppins · 2017-05-09T09:45:59Z

The angular.io preview for 151d795 is available here.

mary-poppins · 2017-05-09T14:17:29Z

The angular.io preview for 68263a1 is available here.

gkalpak

LGTM (with a few minor comments/questions).

gkalpak · 2017-05-09T16:27:34Z

aio/content/guide/aot-compiler.md

-  <figure class='image-display'>
-    <img src="generated/images/guide/aot-compiler/toh-pt6-bundle.png" alt="toh-pt6-bundle"></img>
+  <figure>
+    <img src="generated/images/guide/aot-compiler/toh-pt6-bundle.png" alt="toh-pt6-bundle" width="700">


This raw image is super big. A width of 700px is about all you can manage on a screen that is at the breakpoint of 1300px before the max-width: 100% kicks in.

Shouldn't we resize the image then (and save the cost of downloading it)?

Yes but that was outside of my remit :-P
I'll create an issue to track it.

gkalpak · 2017-05-09T16:37:34Z

aio/content/guide/upgrade.md

-<figure class='image-display'>
-  <img src="generated/images/guide/upgrade/injectors.png" alt="The two injectors in a hybrid application" width="700"></img>
+<figure>
+  <img src="generated/images/guide/upgrade/injectors.png" alt="The two injectors in a hybrid application" width="700" height="262">


Why do we need manualy width/height here?

The actual image is too large for the width of the page at the breakpoint where we switch to max-width: 100% and height: auto. 700 is the biggest width that works at this screen width.

gkalpak · 2017-05-09T16:45:10Z

aio/content/guide/reactive-forms.md

-<figure class='image-display'>
-  <img src="generated/images/guide/reactive-forms/json-output.png" width="400px" alt="JSON output"></img>
+<figure>
+  <img src="generated/images/guide/reactive-forms/json-output.png" width="400" height="133" alt="JSON output">


How did you determine these heights. This one looks "sqeezed" for example?

I was going to comment this one too.

For each image I set the width to the suggested width and then checked that the browser resized the height to. I may have got it wrong in this case. It should have been 176.

gkalpak · 2017-05-09T16:54:21Z

aio/src/styles/2-modules/_images.scss

+
+    &.right {
+      float: right;
+      margin-left: 20px;


This left margin doesn't look so goodon narrow screens (where max-width: 100%).

Good call, we need to lose the floating when narrow, I guess.

gkalpak · 2017-05-09T17:00:28Z

aio/content/guide/architecture.md


 <figure>
-  <img src="generated/images/guide/architecture/parent-child-binding.png" alt="Parent/Child binding" style="float:left; width:300px; margin-left:-40px;margin-right:10px"></img>
+  <img src="generated/images/guide/architecture/parent-child-binding.png" alt="Parent/Child binding" width="400">


Nit: I think the idea was to make this image the same size as the previous one (which looks better). This behavior is not retained here.

agreed - will fix

gkalpak · 2017-05-09T17:06:16Z

aio/tools/transforms/angular.io-package/index.js

@@ -42,4 +42,5 @@ module.exports = new Package('angular.io', [gitPackage, apiPackage, contentPacka
        return (existsSync(resolve(SRC_PATH, url)));
      }
    });
+    checkAnchorLinksProcessor.pathVariants = ['', '/', '.html', '/index.html', '#top-of-page'];


What is .html for?

The .html is only there because the defaults for that processor were: ['', '/', '.html', '/index.html'], so I am really just adding one new one. :-)

you'd have never known if I'd just used .push('#....').

Don't be so sure 😉

mary-poppins · 2017-05-09T17:15:59Z

The angular.io preview for f66dc2e is available here.

wardbell

Same question. I do like baking #top-of-page though.

Otherwise, lgtm

Foxandxss · 2017-05-09T19:59:45Z

aio/content/guide/reactive-forms.md

-<figure class='image-display'>
-  <img src="generated/images/guide/reactive-forms/json-output.png" width="400px" alt="JSON output"></img>
+<figure>
+  <img src="generated/images/guide/reactive-forms/json-output.png" width="400" height="133" alt="JSON output">


I was going to comment this one too.

Foxandxss · 2017-05-09T20:00:21Z

aio/content/guide/set-document-title.md

@@ -29,7 +29,7 @@ See the <live-example name="set-document-title"></live-example>.
    </td>

    <td>
-      <img src='generated/images/plunker/plunker-switch-to-editor-button.png' width="200px" height="70px" alt="pop out the window" align="right"></img>      <br></br>      <img src='generated/images/plunker/plunker-separate-window-button.png' width="200px" height="47px" alt="pop out the window" align="right"></img>
+      <img src='generated/images/plunker/plunker-switch-to-editor-button.png' width="200" height="70" alt="pop out the window" align="right">      <br></br>      <img src='generated/images/plunker/plunker-separate-window-button.png' width="200" height="47" alt="pop out the window" align="right">


This in narrow mode is almost invisible.

Hmm, that is because the image is in a td and it's width gets set to max-width: 100% but that it 100% of the td rather than the page. We might need some additional styling to cope with this situation.

Actually using a table is not right here. It is much better to use a subsection and floating images. I'll fix up.

Foxandxss · 2017-05-09T20:05:31Z

The embedded plunker preview images are suuuuuuuuuper big.

petebacondarwin · 2017-05-09T21:57:27Z

I fixed the embedded plunker images.

The css rules for `img.right` and `img.left` allow authors easy access to floating an image on the left or right, respectively. The `.image-display` rule which was always found on a figure has been simplified so that all figures have this styling. It is very unlikely that a figure will be used outside the content area; and at this time it seems like `figure` is as good an indicator that we want this kind of styling as anything. Now that images are all tagged with width and height values, we cannot assume to modify these dimensions via CSS as it can cause the image to lose its correct proportions. Until we find a better solition we must set `height` to `auto` when the screen width is below 1300px to ensure that these images maintain their proportions as they get shrunk to fit.

Previously the negative margin on the code headings were causing floated images to overlay the start of a code block. Now all code block successfully clear all floated elements.

Previously, the guides have a lot of inline image styling and unnecessary use of the `image-display` css class. Images over 700px are problematic for guide docs, so those have been given specific widths and associated heights.

The `#toc` anchor does not work when the page is wide enough that the TOC is floating to the side.

Since the `#top-of-page` is outside the rendered docs the `checkAnchorLinks` processor doesn't find them as valid targets for links. Adding them as a `pathVariant` solves this problem but will still catch links to docs that do not actually exist.

This made them look too big, generally. Leaving them with no size means that they will look reasonable in large viewports and switch to 100% width in narrow viewports.

petebacondarwin · 2017-05-09T22:09:23Z

I think this is all fixed up @Foxandxss and @gkalpak PTAL

mary-poppins · 2017-05-09T22:12:53Z

The angular.io preview for 84b16a1 is available here.

mary-poppins · 2017-05-09T22:22:42Z

The angular.io preview for 1802c5c is available here.

Foxandxss · 2017-05-09T22:27:05Z

Works for me pete.

* fix(aio): allow code blocks to clear floated images Previously the negative margin on the code headings were causing floated images to overlay the start of a code block. Now all code block successfully clear all floated elements. * feat(aio): add a `.clear` class for clearing floating images * fix(aio): tidy up image styles The css rules for `img.right` and `img.left` allow authors easy access to floating an image on the left or right, respectively. The `.image-display` rule which was always found on a figure has been simplified so that all figures have this styling. It is very unlikely that a figure will be used outside the content area; and at this time it seems like `figure` is as good an indicator that we want this kind of styling as anything. Now that images are all tagged with width and height values, we cannot assume to modify these dimensions via CSS as it can cause the image to lose its correct proportions. Until we find a better solition we must set `height` to `auto` when the screen width is below 1300px to ensure that these images maintain their proportions as they get shrunk to fit. * docs(aio): general tidy up of image HTML in guides Previously, the guides have a lot of inline image styling and unnecessary use of the `image-display` css class. Images over 700px are problematic for guide docs, so those have been given specific widths and associated heights. * docs(aio): use correct anchor for "back to the top" link The `#toc` anchor does not work when the page is wide enough that the TOC is floating to the side. * build(aio): add `#top-of-page` to path variants for link checking Since the `#top-of-page` is outside the rendered docs the `checkAnchorLinks` processor doesn't find them as valid targets for links. Adding them as a `pathVariant` solves this problem but will still catch links to docs that do not actually exist. * fix(aio): ensure that headings clear floated images * fix(aio): do not force live-example embedded image to 100% size This made them look too big, generally. Leaving them with no size means that they will look reasonable in large viewports and switch to 100% width in narrow viewports.

angular-automatic-lock-bot · 2019-09-11T13:21:43Z

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}

petebacondarwin added comp: aio state: WIP labels May 6, 2017

petebacondarwin self-assigned this May 6, 2017

googlebot added the cla: yes label May 6, 2017

petebacondarwin added this to WIP in docs-infra May 6, 2017

petebacondarwin force-pushed the aio-image-sweep branch from c13cd25 to 8294ad3 Compare May 6, 2017 16:49

petebacondarwin assigned wardbell and unassigned petebacondarwin May 6, 2017

petebacondarwin force-pushed the aio-image-sweep branch from 025c329 to 9475ec7 Compare May 7, 2017 15:02

petebacondarwin force-pushed the aio-image-sweep branch from 9475ec7 to 383ad5e Compare May 7, 2017 17:50

petebacondarwin force-pushed the aio-image-sweep branch from ff25d22 to f487edb Compare May 8, 2017 22:14

petebacondarwin changed the title ~~aio": image sweep (WIP)~~ docs(aio): image sweep May 9, 2017

petebacondarwin added action: review The PR is still awaiting reviews from at least one requested reviewer and removed state: WIP labels May 9, 2017

petebacondarwin commented May 9, 2017

View reviewed changes

petebacondarwin force-pushed the aio-image-sweep branch from f487edb to 151d795 Compare May 9, 2017 09:28

petebacondarwin moved this from WIP to REVIEW in docs-infra May 9, 2017

petebacondarwin force-pushed the aio-image-sweep branch from 151d795 to 68263a1 Compare May 9, 2017 13:58

gkalpak approved these changes May 9, 2017

View reviewed changes

wardbell reviewed May 9, 2017

View reviewed changes

Foxandxss reviewed May 9, 2017

View reviewed changes

petebacondarwin force-pushed the aio-image-sweep branch from f66dc2e to 84b16a1 Compare May 9, 2017 21:57

petebacondarwin added 8 commits May 9, 2017 23:04

fix(aio): allow code blocks to clear floated images

fafa075

Previously the negative margin on the code headings were causing floated images to overlay the start of a code block. Now all code block successfully clear all floated elements.

feat(aio): add a .clear class for clearing floating images

07043fa

docs(aio): general tidy up of image HTML in guides

d7f6068

Previously, the guides have a lot of inline image styling and unnecessary use of the `image-display` css class. Images over 700px are problematic for guide docs, so those have been given specific widths and associated heights.

docs(aio): use correct anchor for "back to the top" link

1bce4e9

The `#toc` anchor does not work when the page is wide enough that the TOC is floating to the side.

fix(aio): ensure that headings clear floated images

901f7ec

fix(aio): do not force live-example embedded image to 100% size

1802c5c

This made them look too big, generally. Leaving them with no size means that they will look reasonable in large viewports and switch to 100% width in narrow viewports.

petebacondarwin force-pushed the aio-image-sweep branch from 84b16a1 to 1802c5c Compare May 9, 2017 22:05

petebacondarwin added action: merge The PR is ready for merge by the caretaker and removed action: review The PR is still awaiting reviews from at least one requested reviewer labels May 9, 2017

petebacondarwin moved this from REVIEW to MERGE in docs-infra May 9, 2017

jasonaden merged commit 9e661e5 into angular:master May 9, 2017

petebacondarwin removed this from MERGE in docs-infra May 9, 2017

petebacondarwin deleted the aio-image-sweep branch May 9, 2017 22:58

angular-automatic-lock-bot bot locked and limited conversation to collaborators Sep 11, 2019

docs(aio): image sweep #16609

docs(aio): image sweep #16609

Conversation

petebacondarwin commented May 6, 2017 • edited

Using Images

Image Size

Image Formatting

Inline Images

Floating images

Standalone images

mary-poppins commented May 6, 2017

mary-poppins commented May 6, 2017

mary-poppins commented May 6, 2017

mary-poppins commented May 7, 2017

mary-poppins commented May 7, 2017

mary-poppins commented May 8, 2017

mary-poppins commented May 8, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mary-poppins commented May 9, 2017

mary-poppins commented May 9, 2017

gkalpak left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

petebacondarwin May 10, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mary-poppins commented May 9, 2017

wardbell left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

petebacondarwin May 9, 2017 • edited

Choose a reason for hiding this comment

Foxandxss commented May 9, 2017

petebacondarwin commented May 9, 2017 • edited

petebacondarwin commented May 9, 2017

mary-poppins commented May 9, 2017

mary-poppins commented May 9, 2017

Foxandxss commented May 9, 2017

angular-automatic-lock-bot bot commented Sep 11, 2019

petebacondarwin commented May 6, 2017 •

edited

petebacondarwin May 10, 2017 •

edited

petebacondarwin May 9, 2017 •

edited

petebacondarwin commented May 9, 2017 •

edited