diff --git a/src/applications/files/remarkup/PhabricatorRemarkupRuleEmbedFile.php b/src/applications/files/remarkup/PhabricatorRemarkupRuleEmbedFile.php
index c631d53fd4..af7d910df0 100644
--- a/src/applications/files/remarkup/PhabricatorRemarkupRuleEmbedFile.php
+++ b/src/applications/files/remarkup/PhabricatorRemarkupRuleEmbedFile.php
@@ -1,219 +1,224 @@
 <?php
 
 final class PhabricatorRemarkupRuleEmbedFile
   extends PhabricatorRemarkupRuleObject {
 
   const KEY_EMBED_FILE_PHIDS = 'phabricator.embedded-file-phids';
 
   protected function getObjectNamePrefix() {
     return 'F';
   }
 
   protected function loadObjects(array $ids) {
     $engine = $this->getEngine();
 
     $viewer = $engine->getConfig('viewer');
     $objects = id(new PhabricatorFileQuery())
       ->setViewer($viewer)
       ->withIDs($ids)
       ->execute();
 
     $phids_key = self::KEY_EMBED_FILE_PHIDS;
     $phids = $engine->getTextMetadata($phids_key, array());
     foreach (mpull($objects, 'getPHID') as $phid) {
       $phids[] = $phid;
     }
     $engine->setTextMetadata($phids_key, $phids);
 
     return $objects;
   }
 
   protected function renderObjectEmbed($object, $handle, $options) {
     $options = $this->getFileOptions($options) + array(
       'name' => $object->getName(),
     );
 
     $is_viewable_image = $object->isViewableImage();
     $is_audio = $object->isAudio();
     $force_link = ($options['layout'] == 'link');
 
     $options['viewable'] = ($is_viewable_image || $is_audio);
 
     if ($is_viewable_image && !$force_link) {
       return $this->renderImageFile($object, $handle, $options);
     } else if ($is_audio && !$force_link) {
       return $this->renderAudioFile($object, $handle, $options);
     } else {
       return $this->renderFileLink($object, $handle, $options);
     }
   }
 
   private function getFileOptions($option_string) {
     $options = array(
       'size'    => null,
       'layout'  => 'left',
       'float'   => false,
       'width'   => null,
       'height'  => null,
+      'alt' => null,
     );
 
     if ($option_string) {
       $option_string = trim($option_string, ', ');
       $parser = new PhutilSimpleOptions();
       $options = $parser->parse($option_string) + $options;
     }
 
     return $options;
   }
 
   private function renderImageFile(
     PhabricatorFile $file,
     PhabricatorObjectHandle $handle,
     array $options) {
 
     require_celerity_resource('lightbox-attachment-css');
 
     $attrs = array();
     $image_class = null;
 
     $use_size = true;
     if (!$options['size']) {
       $width = $this->parseDimension($options['width']);
       $height = $this->parseDimension($options['height']);
       if ($width || $height) {
         $use_size = false;
         $attrs += array(
           'src' => $file->getBestURI(),
           'width' => $width,
           'height' => $height,
         );
       }
     }
 
     if ($use_size) {
       switch ((string)$options['size']) {
         case 'full':
           $attrs += array(
             'src' => $file->getBestURI(),
             'width' => $file->getImageWidth(),
             'height' => $file->getImageHeight(),
           );
           $image_class = 'phabricator-remarkup-embed-image-full';
           break;
         case 'thumb':
         default:
           $attrs['src'] = $file->getPreview220URI();
           $dimensions =
             PhabricatorImageTransformer::getPreviewDimensions($file, 220);
           $attrs['width'] = $dimensions['sdx'];
           $attrs['height'] = $dimensions['sdy'];
           $image_class = 'phabricator-remarkup-embed-image';
           break;
       }
     }
 
+    if (isset($options['alt'])) {
+      $attrs['alt'] = $options['alt'];
+    }
+
     $img = phutil_tag('img', $attrs);
 
     $embed = javelin_tag(
       'a',
       array(
         'href'        => $file->getBestURI(),
         'class'       => $image_class,
         'sigil'       => 'lightboxable',
         'meta'        => array(
           'phid' => $file->getPHID(),
           'uri' => $file->getBestURI(),
           'dUri' => $file->getDownloadURI(),
           'viewable' => true,
         ),
       ),
       $img);
 
     switch ($options['layout']) {
       case 'right':
       case 'center':
       case 'inline':
       case 'left':
         $layout_class = 'phabricator-remarkup-embed-layout-'.$options['layout'];
         break;
       default:
         $layout_class = 'phabricator-remarkup-embed-layout-left';
         break;
     }
 
     if ($options['float']) {
       switch ($options['layout']) {
         case 'center':
         case 'inline':
           break;
         case 'right':
           $layout_class .= ' phabricator-remarkup-embed-float-right';
           break;
         case 'left':
         default:
           $layout_class .= ' phabricator-remarkup-embed-float-left';
           break;
       }
     }
 
     return phutil_tag(
       'div',
       array(
         'class' => $layout_class,
       ),
       $embed);
   }
 
   private function renderAudioFile(
     PhabricatorFile $file,
     PhabricatorObjectHandle $handle,
     array $options) {
 
     if (idx($options, 'autoplay')) {
       $preload = 'auto';
       $autoplay = 'autoplay';
     } else {
       $preload = 'none';
       $autoplay = null;
     }
 
     return phutil_tag(
       'audio',
       array(
         'controls' => 'controls',
         'preload' => $preload,
         'autoplay' => $autoplay,
         'loop' => idx($options, 'loop') ? 'loop' : null,
       ),
       phutil_tag(
         'source',
         array(
           'src' => $file->getBestURI(),
           'type' => $file->getMimeType(),
         )));
   }
 
   private function renderFileLink(
     PhabricatorFile $file,
     PhabricatorObjectHandle $handle,
     array $options) {
 
     return id(new PhabricatorFileLinkView())
       ->setFilePHID($file->getPHID())
       ->setFileName($options['name'])
       ->setFileDownloadURI($file->getDownloadURI())
       ->setFileViewURI($file->getBestURI())
       ->setFileViewable($options['viewable']);
   }
 
   private function parseDimension($string) {
     $string = trim($string);
 
     if (preg_match('/^(?:\d*\\.)?\d+%?$/', $string)) {
       return $string;
     }
 
     return null;
   }
 
 }
diff --git a/src/applications/macro/remarkup/PhabricatorRemarkupRuleMeme.php b/src/applications/macro/remarkup/PhabricatorRemarkupRuleMeme.php
index 637d25ffa7..88c754ff37 100644
--- a/src/applications/macro/remarkup/PhabricatorRemarkupRuleMeme.php
+++ b/src/applications/macro/remarkup/PhabricatorRemarkupRuleMeme.php
@@ -1,49 +1,56 @@
 <?php
 
 /**
  * @group markup
  */
 final class PhabricatorRemarkupRuleMeme
   extends PhutilRemarkupRule {
 
   private $images;
 
   public function apply($text) {
     return preg_replace_callback(
       '@{meme,((?:[^}\\\\]+|\\\\.)+)}$@m',
       array($this, 'markupMeme'),
       $text);
   }
 
   public function markupMeme($matches) {
     $options = array(
       'src' => null,
       'above' => null,
       'below' => null,
     );
 
     $parser = new PhutilSimpleOptions();
     $options = $parser->parse($matches[1]) + $options;
 
     $uri = id(new PhutilURI('/macro/meme/'))
       ->alter('macro', $options['src'])
       ->alter('uppertext', $options['above'])
       ->alter('lowertext', $options['below']);
 
     if ($this->getEngine()->isTextMode()) {
       $img =
         ($options['above'] != '' ? "\"{$options['above']}\"\n" : '').
         $options['src'].' <'.PhabricatorEnv::getProductionURI($uri).'>'.
         ($options['below'] != '' ? "\n\"{$options['below']}\"" : '');
     } else {
+      $alt_text = pht(
+        'Macro %s: %s %s',
+        $options['src'],
+        $options['above'],
+        $options['below']);
+
       $img = phutil_tag(
         'img',
         array(
           'src' => (string)$uri,
+          'alt' => $alt_text,
         ));
     }
 
     return $this->getEngine()->storeText($img);
   }
 
 }
diff --git a/src/docs/user/userguide/remarkup.diviner b/src/docs/user/userguide/remarkup.diviner
index b15dcc0e35..ab671649e1 100644
--- a/src/docs/user/userguide/remarkup.diviner
+++ b/src/docs/user/userguide/remarkup.diviner
@@ -1,517 +1,518 @@
 @title Remarkup Reference
 @group userguide
 
 Explains how to make bold text; this makes your words louder so you can win
 arguments.
 
 = Overview =
 
 Phabricator uses a lightweight markup language called "Remarkup", similar to
 other lightweight markup languages like Markdown and Wiki markup.
 
 This document describes how to format text using Remarkup.
 
 = Quick Reference =
 
 All the syntax is explained in more detail below, but this is a quick guide to
 formatting text in Remarkup.
 
 These are inline styles, and can be applied to most text:
 
   **bold** //italic// ##monospaced## `monospaced` ~~deleted~~ __underlined__
   D123 T123 rX123           # Link to Objects
   {D123} {T123}             # Link to Objects (Full Name)
   {F123}                    # Embed Images
   @username                 # Mention a user
   [[wiki page]]             # Link to Phriction
   [[wiki page | name]]      # Named link to Phriction
   http://xyz/               # Link to web
   [[http://xyz/ | name]]    # Named link to web
   [name](http://xyz/)       # Alternate Link
 
 These are block styles, and must be separated from surrounding text by
 empty lines:
 
   = Large Header =
 
   == Smaller Header ==
 
   Also a Large Header
   ===================
 
   Also a Smaller Header
   ---------------------
 
   > Quoted Text
 
   Use "- " or "* " for bulleted lists, and "# " for numbered lists.
   Use ``` or indent two spaces for code.
   Use %%% for a literal block.
   Use | ... | ... for tables.
 
 = Basic Styling =
 
 Format **basic text styles** like this:
 
   **bold text**
   //italic text//
   ##monospaced text##
   `monospaced text`
   ~~deleted text~~
   __underlined text__
 
 Those produce **bold text**, //italic text//, ##monospaced text##,
 `monospaced text`, ~~deleted text~~, and __underlined text__, respectively.
 
 = Layout =
 
 Make **headers** like this:
 
   = Large Header =
 
   == Smaller Header ==
 
   ===== Very Small Header =====
 
   Alternate Large Header
   ======================
 
   Alternate Smaller Header
   ------------------------
 
 You can optionally omit the trailing `=` signs -- that is, these are the same:
 
   == Smaller Header ==
 
   == Smaller Header
 
 This produces headers like the ones in this document. Make sure you have an
 empty line before and after the header.
 
 Make **lists** by beginning each item with a "-" or a "*":
 
   lang=text
   - milk
   - eggs
   - bread
 
   * duck
   * duck
   * goose
 
 This produces a list like this:
 
   - milk
   - eggs
   - bread
 
 (Note that you need to put a space after the "-" or "*".)
 
 You can make numbered lists with a "#" instead of "-" or "*":
 
   # Articuno
   # Zapdos
   # Moltres
 
 You can also nest lists:
 
 ```- Body
   - Head
   - Arm
     - Elbow
     - Hand
       # Thumb
       # Index
       # Middle
       # Ring
       # Pinkie
   - Leg
     - Knee
     - Foot```
 
 ...which produces:
 
   - Body
   - Head
   - Arm
     - Elbow
     - Hand
       # Thumb
       # Index
       # Middle
       # Ring
       # Pinkie
   - Leg
     - Knee
     - Foot
 
 If you prefer, you can indent lists using multiple characters to show indent
 depth, like this:
 
 ```- Tree
 -- Branch
 --- Twig```
 
 As expected, this produces:
 
 - Tree
 -- Branch
 --- Twig
 
 Make **code blocks** by indenting two spaces:
 
   f(x, y);
 
 You can also use three backticks to enclose the code block:
 
   ```f(x, y);
   g(f);```
 
 You can specify a language for syntax highlighting with "lang=xxx":
 
   lang=text
   lang=html
   <a href="#">...</a>
 
 This will highlight the block using a highlighter for that language, if one is
 available (in most cases, this means you need to configure Pygments):
 
   lang=html
   <a href="#">...</a>
 
 You can also use a "COUNTEREXAMPLE" header to show that a block of code is
 bad and shouldn't be copied:
 
   lang=text
   COUNTEREXAMPLE
   function f() {
     global $$variable_variable;
   }
 
 This produces a block like this:
 
   COUNTEREXAMPLE
   function f() {
     global $$variable_variable;
   }
 
 You can use ##lines=N## to limit the vertical size of a chunk of code, and
 ##name=some_name.ext## to give it a name. For example, this:
 
   lang=text
   lang=html, name=example.html, lines=12, counterexample
   ...
 
 ...produces this:
 
   lang=html, name=example.html, lines=12, counterexample
   <p>Apple</p>
   <p>Apricot</p>
   <p>Avocado</p>
   <p>Banana</p>
   <p>Bilberry</p>
   <p>Blackberry</p>
   <p>Blackcurrant</p>
   <p>Blueberry</p>
   <p>Currant</p>
   <p>Cherry</p>
   <p>Cherimoya</p>
   <p>Clementine</p>
   <p>Date</p>
   <p>Damson</p>
   <p>Durian</p>
   <p>Eggplant</p>
   <p>Elderberry</p>
   <p>Feijoa</p>
   <p>Gooseberry</p>
   <p>Grape</p>
   <p>Grapefruit</p>
   <p>Guava</p>
   <p>Huckleberry</p>
   <p>Jackfruit</p>
   <p>Jambul</p>
   <p>Kiwi fruit</p>
   <p>Kumquat</p>
   <p>Legume</p>
   <p>Lemon</p>
   <p>Lime</p>
   <p>Lychee</p>
   <p>Mandarine</p>
   <p>Mango</p>
   <p>Mangostine</p>
   <p>Melon</p>
 
 You can also use "NOTE:", "WARNING:", or "IMPORTANT:" to call out an important
  idea.
 
 NOTE: Best practices in proton pack operation include not crossing the streams.
 
 WARNING: Crossing the streams can result in total protonic reversal!
 
 IMPORTANT: Don't cross the streams!
 
 You can also use "(NOTE)", "(WARNING)", or "(IMPORTANT)" to get the same
  effect but without "(NOTE"), "(WARNING)", or "(IMPORTANT)" appearing in the
  rendered result. For example
 
 (NOTE) Dr. Egon Spengler is the best resource for additional proton pack
  questions.
 
 = Linking URIs =
 
 URIs are automatically linked: http://phabricator.org/
 
 If you have a URI with problematic characters in it, like
 "##http://comma.org/,##", you can surround it with angle brackets:
 
   <http://comma.org/,>
 
 This will force the parser to consume the whole URI: <http://comma.org/,>
 
 You can also use create named links, where you choose the displayed text. These
 work within Phabricator or on the internet at large:
 
   [[/herald/transcript/ | Herald Transcripts]]
   [[http://www.boring-legal-documents.com/ | exciting legal documents]]
 
 Markdown-style links are also supported:
 
   [Toil](http://www.trouble.com)
 
 = Linking to Objects =
 
 You can link to Differential revisions, Diffusion commits and Maniphest tasks
 by mentioning the name of an object:
 
   D123          # Link to Differential revision D123
   rX123         # Link to SVN commit 123 from the "X" repository
   rXaf3192cd5   # Link to Git commit "af3192cd5..." from the "X" repository.
                 # You must specify at least 7 characters of the hash.
   T123          # Link to Maniphest task T123
 
 You can also link directly to a comment in Maniphest and Differential:
 
   T123#4        # Link to comment #4 of T123
 
 = Embedding Objects
 
 You can also generate full-name references to some objects by using braces:
 
   {D123}        # Link to Differential revision D123 with the full name
   {T123}        # Link to Maniphest task T123 with the full name
 
 These references will also show when an object changes state (for instance, a
 task or revision is closed). Some types of objects support rich embedding.
 
 == Embedding Mocks (Pholio)
 
 You can embed a Pholio mock by using braces to refer to it:
 
   {M123}
 
 By default the first four images from the mock set are displayed. This behavior
 can be overridden with the **image** option. With the **image** option you can
 provide one or more image IDs to display.
 
 You can set the image (or images) to display like this:
 
   {M123, image=12345}
   {M123, image=12345 & 6789}
 
 == Embedding Pastes
 
 You can embed a Paste using braces:
 
   {P123}
 
 You can adjust the embed height with the `lines` option:
 
   {P123, lines=15}
 
 You can highlight specific lines with the `highlight` option:
 
   {P123, highlight=15}
   {P123, highlight="23-25, 31"}
 
 == Embedding Images
 
 You can embed an image or other file by using braces to refer to it:
 
   {F123}
 
 In most interfaces, you can drag-and-drop an image from your computer into the
 text area to upload and reference it.
 
 Some browsers (e.g. Chrome) support uploading an image data just by pasting them
 from clipboard into the text area.
 
 You can set file display options like this:
 
-  {F123, layout=left, float, size=full}
+  {F123, layout=left, float, size=full, alt="a duckling"}
 
 Valid options are:
 
   - **layout** left (default), center, right, inline, link (render a link
     instead of a thumbnail for images)
   - **float** If layout is set to left or right, the image will be floated so
     text wraps around it.
   - **size** thumb (default), full
   - **name** with `layout=link` or for non-images, use this name for the link
     text
   - **width** Scale image to a specific width.
   - **height** Scale image to a specific height.
+  - **alt** Provide alternate text for assistive technologies.
 
 == Embedding Countdowns
 
 You can embed a countdown by using braces:
 
   {C123}
 
 = Quoting Text =
 
 To quote text, preface it with an ">":
 
   > This is quoted text.
 
 This appears like this:
 
 > This is quoted text.
 
 = Embedding Media =
 
 If you set a configuration flag, you can embed media directly in text:
 
   - **remarkup.enable-embedded-youtube**: allows you to paste in YouTube videos
     and have them render inline.
 
 This option is disabled by default because it has security and/or
 silliness implications. Read the description in ##default.conf.php## before
 enabling it.
 
 = Image Macros =
 
 You can upload image macros (More Stuff -> Macro) which will replace text
 strings with the image you specify. For instance, you could upload an image of a
 dancing banana to create a macro named "peanutbutterjellytime", and then any
 time you type that string on a separate line it will be replaced with the image
 of a dancing banana.
 
 = Memes =
 
 You can also use image macros in the context of memes. For example, if you
 have an image macro named "grumpy", you can create a meme by doing the
 following:
 
   {meme, src = grumpy, above = toptextgoeshere, below = bottomtextgoeshere}
 
 By default, the font used to create the text for the meme is `tuffy.ttf`. For
 the more authentic feel of `impact.ttf`, you simply have to place the Impact
 TrueType font in the Phabricator subfolder `/resources/font/`. If Remarkup
 detects the presence of `impact.ttf`, it will automatically use it.
 
 = Mentioning Users =
 
 In Differential and Maniphest, you can mention another user by writing:
 
   @username
 
 When you submit your comment, this will add them as a CC on the revision or task
 if they aren't already CC'd.
 
 = Phriction Documents =
 
 You can link to Phriction documents with a name or path:
 
   Make sure you sign and date your [[legal/Letter of Marque and Reprisal]]!
 
 With a pipe (##|##), you can retitle the link. Use this to mislead your
 opponents:
 
   Check out these [[legal/boring_documents/ | exciting legal documents]]!
 
 = Literal Blocks =
 
 To place text in a literal block use "%%%":
 
   %%%Text that won't be processed by remarkup
   [[http://www.example.com | example]]
   %%%
 
 Remarkup will not process the text inside of literal blocks (other than to
 escape HTML and preserve line breaks).
 
 = Tables =
 
 Remarkup supports simple table syntax. For example, this:
 
   | Fruit  | Color  | Price   | Peel?
   | -----  | -----  | -----   | -----
   | Apple  | red    | `$0.93` | no
   | Banana | yellow | `$0.19` | **YES**
 
 ...produces this:
 
 | Fruit  | Color  | Price   | Peel?
 | -----  | -----  | -----   | -----
 | Apple  | red    | `$0.93` | no
 | Banana | yellow | `$0.19` | **YES**
 
 Remarkup also supports a simplified HTML table syntax. For example, this:
 
   <table>
     <tr>
       <th>Fruit</th>
       <th>Color</th>
       <th>Price</th>
       <th>Peel?</th>
     </tr>
     <tr>
       <td>Apple</td>
       <td>red</td>
       <td>`$0.93`</td>
       <td>no</td>
     </tr>
     <tr>
       <td>Banana</td>
       <td>yellow</td>
       <td>`$0.19`</td>
       <td>**YES**</td>
     </tr>
   </table>
 
 ...produces this:
 
 <table>
   <tr>
     <th>Fruit</th>
     <th>Color</th>
     <th>Price</th>
     <th>Peel?</th>
   </tr>
   <tr>
     <td>Apple</td>
     <td>red</td>
     <td>`$0.93`</td>
     <td>no</td>
   </tr>
   <tr>
     <td>Banana</td>
     <td>yellow</td>
     <td>`$0.19`</td>
     <td>**YES**</td>
   </tr>
 </table>
 
 Some general notes about this syntax:
 
   - your tags must all be properly balanced;
   - your tags must NOT include attributes (`<td>` is OK, `<td style="...">` is
     not);
   - you can use other Remarkup rules (like **bold**, //italics//, etc.) inside
     table cells.
 
 = Fullscreen Mode =
 
 Remarkup editors provide a fullscreen composition mode.  This can make it easier
 to edit large blocks of text, or improve focus by removing distractions. You can
 exit **Fullscreen** mode by clicking the button again or by pressing escape.