docs: improve alt messages (#8047)

packages/docusaurus-logger/README.md

@@ -57,4 +57,4 @@ An embedded expression is optionally preceded by a flag in the form `[a-z]+=` (a
 
 If the expression is an array, it's formatted by `` `\n- ${array.join('\n- ')}\n` `` (note it automatically gets a leading line end). Each member is formatted by itself and the bullet is not formatted. So you would see the above message printed as:
 
-![demo](./demo.png)
+![Some text output in the terminal, containing array, code, name, and number formatting](./demo.png)

website/blog/2017-12-14-introducing-docusaurus.md

@@ -4,7 +4,7 @@ authors: JMarcey
 tags: [documentation, blog, docusaurus]
 ---
 
-![Introducing Slash](/img/slash-introducing.svg)
+![](/img/slash-introducing.svg)
 
 We are very happy to introduce [Docusaurus](https://github.com/facebook/docusaurus) to help you manage one or many open source websites.
 
@@ -23,7 +23,7 @@ Docusaurus also provides core website and documentation features out-of-the-box
 
 ## The Birth of docusaurus
 
-![Birth of Slash](/img/slash-birth.png)
+![](/img/slash-birth.png)
 
 When Facebook first started their open source program, many teams implemented a custom website for each of their open source projects. This approach presented challenges when the open source program team was asked to help the project teams improve their documentation. Since each site was unique, adding basic infrastructure such as a blog, consistent navigation, search, etc. became challenging undertakings.
 
@@ -39,7 +39,7 @@ At Facebook, Docusaurus allows us to quickly get different projects up and runni
 
 ## Getting Up and Running
 
-![Slash Up and Running](/img/slash-up-and-running.png)
+![](/img/slash-up-and-running.png)
 
 At its core, we wanted sites running Docusaurus to be simple to use. With one [installation](https://v1.docusaurus.io/docs/en/installation.html) command and some simple [configuration](https://v1.docusaurus.io/docs/en/site-preparation.html), you can actually have a default running website.
 
@@ -127,7 +127,7 @@ build
 
 ## Community
 
-![Docusaurus](/img/docusaurus.svg)
+![](/img/docusaurus.svg)
 
 We welcome your [contributions](https://github.com/facebook/docusaurus/blob/master/CONTRIBUTING.md) to Docusaurus, whether you want to use it for your own site, you want to [contribute](https://github.com/facebook/docusaurus/blob/master/CONTRIBUTING.md) to the Docusaurus core or just have questions. Follow us on [GitHub](https://github.com/facebook/docusaurus) and [Twitter](https://twitter.com/docusaurus).
 

website/blog/2018-04-30-How-I-Converted-Profilo-To-Docusaurus.md

@@ -46,73 +46,77 @@ Here's an overview of the steps taken to convert to a website. I'll discuss some
 
 **Content creation:**
 
-1.  Added metadata to the existing Markdown files found in the `docs` folder, for example:
-
-        +---
-        +id: architecture
-        +title: Architecture
-        +sidebar_label: Architecture
-        +---
-
-1.  Added the logo assets to the `website/static/img` folder.
-1.  Modified `website/pages/en/index.js`, the landing page, to highlight Profilo features.
-1.  Modified `website/core/Footer.js`, the footer, to simplify it for Profilo.
-1.  Edited `website/siteConfig.js` (website configuration file) to specify the previously chosen primary and secondary colors.
-1.  Modified `website/sidebars.json` that specifies the sidebar navigation. Listed all the docs and customized it based on the metadata added to the Markdown files.
-1.  Edited the website configuration file to specify the GitHub properties, logo images, header links, and the website link.
-1.  Tested the website locally throughout this phase. (I ran `yarn start` from the `website` folder to start the server.)
+1. Added metadata to the existing Markdown files found in the `docs` folder, for example:
+
+   ```md
+   ---
+   id: architecture
+   title: Architecture
+   sidebar_label: Architecture
+   ---
+   ```
+
+2. Added the logo assets to the `website/static/img` folder.
+3. Modified `website/pages/en/index.js`, the landing page, to highlight Profilo features.
+4. Modified `website/core/Footer.js`, the footer, to simplify it for Profilo.
+5. Edited `website/siteConfig.js` (website configuration file) to specify the previously chosen primary and secondary colors.
+6. Modified `website/sidebars.json` that specifies the sidebar navigation. Listed all the docs and customized it based on the metadata added to the Markdown files.
+7. Edited the website configuration file to specify the GitHub properties, logo images, header links, and the website link.
+8. Tested the website locally throughout this phase. (I ran `yarn start` from the `website` folder to start the server.)
 
 **Feedback and review changes:**
 
 1. Sent a [pull request](https://github.com/facebookincubator/profilo/pull/6) to the project.
-1. Updated the colors after the designer rightly gasped at the ones I had chosen (IANAD).
-1. Updated the colors and updated the PR.
-1. The PR was then accepted and [merged](https://github.com/facebookincubator/profilo/commit/6ad033aaf5a7d54e6d842f45a5bccd051a8e45ad). Yay!
+2. Updated the colors after the designer rightly gasped at the ones I had chosen (IANAD).
+3. Updated the colors and updated the PR.
+4. The PR was then accepted and [merged](https://github.com/facebookincubator/profilo/commit/6ad033aaf5a7d54e6d842f45a5bccd051a8e45ad). Yay!
 
 **Website publishing:**
 
-1.  Pushed the first website version by running the Docusaurus publish script from the command line:
+1. Pushed the first website version by running the Docusaurus publish script from the command line:
 
-        USE_SSH=true \
-          GIT_USER=caabernathy \
-          CURRENT_BRANCH=master \
-          yarn run publish-gh-pages
+   ```bash
+   USE_SSH=true \
+     GIT_USER=caabernathy \
+     CURRENT_BRANCH=master \
+     yarn run publish-gh-pages
+   ```
 
-1.  Configured CircleCI using the [provided Docusaurus instructions](https://v1.docusaurus.io/docs/en/publishing.html#automating-deployments-using-continuous-integration). There were 2 PRs for this, [the first](https://github.com/facebookincubator/profilo/pull/8)for the initial config and [the second](https://github.com/facebookincubator/profilo/pull/12) to make sure CircleCI only triggered for changes in the master branch (thanks Joel Marcey!).
+2. Configured CircleCI using the [provided Docusaurus instructions](https://v1.docusaurus.io/docs/en/publishing.html#automating-deployments-using-continuous-integration). There were 2 PRs for this, [the first](https://github.com/facebookincubator/profilo/pull/8)for the initial config and [the second](https://github.com/facebookincubator/profilo/pull/12) to make sure CircleCI only triggered for changes in the master branch (thanks Joel Marcey!).
 
 The final website was published on https://facebookincubator.github.io/profilo/. It had taken 1.5 hours to get to the initial PR stage and another half an hour or so to respond to review feedback and publish the website.
 
 ## Design
 
 Here's what the initial website looked like when the first pull request was sent out:
 
-![Website Initial Design](/img/profilo_blog_post_website_initial.png)
+![The website's front page, with a quite bright and saturated red color as the primary color, closely resembling the Profilo logo color, making the logo unrecognizable in the navbar](/img/profilo_blog_post_website_initial.png)
 
 Most of the time in the content creation was spent picking colors that worked reasonably well with the given logo. These colors were a good jumping off point for designer feedback. I used Photoshop to sample various portions of the logo.
 
-![Picking Color Photoshop](/img/profilo_blog_post_photoshop_color_picker.png)
+![Picking colors in Photoshop, with the Profilo logo and the main working area in the background and a color picker dialog in the foreground, selected to a red shade](/img/profilo_blog_post_photoshop_color_picker.png)
 
 I then took the RGB representation of the color and set it as the baseline color on [Paletton](http://paletton.com/). The website then gave me various color options to try on the website by editing the Docusaurus website configuration file.
 
-![Picking Color Paletton](/img/profilo_blog_post_palette_website_color_picker.png)
+![Using Paletton to generate a full palette from the red shade selected. There's a color wheel showing all hues on the left, and a square showing various shades of red on the right.](/img/profilo_blog_post_palette_website_color_picker.png)
 
 The selected primary and secondary colors were a good jumping off point for designer feedback.
 
 There were also modifications made to the default website generated by Docusaurus. These changes were mainly around simplifying the footer and creating a customized landing page for Profilo that listed the project's features.
 
 Here's what the final website looked like:
 
-![Website Final Design](/img/profilo_blog_post_website_final.png)
+![The website's front page, with a much darker red color as the primary color, making both the logo and the primary-colored title text clearly legible.](/img/profilo_blog_post_website_final.png)
 
 This is an example page showing the core content, in this case the Getting Started page:
 
-![Website Docs Example](/img/profilo_blog_post_website_final_docs.png)
+![A doc page with the sidebar on the left quarter of the screen and the main content occupying the rest. Some text is using the primary color and the main body uses multiple kinds of typesetting including bold, list, and code](/img/profilo_blog_post_website_final_docs.png)
 
 This also shows the sidebar structure that was set up through editing `website/sidebars.json`.
 
 Lastly, I didn't have to worry about handling responsive design. You get this out of the box with Docusaurus!
 
-![Mobile Site](/img/profilo_blog_post_android_ios.png)
+![Mobile screenshots of the front page and sample doc page. The layout is automatically adjusted to make it appear more natural. The doc sidebar is hidden behind a button.](/img/profilo_blog_post_android_ios.png)
 
 ## Final Thoughts
 

website/blog/2018-12-14-Happy-First-Birthday-Slash.md

@@ -6,7 +6,7 @@ authors:
 tags: [birth]
 ---
 
-![First Birthday Slash](/img/docusaurus-slash-first-birthday.svg)
+![Docusaurus makes 1 year! Happy Birthday Slash!](/img/docusaurus-slash-first-birthday.svg)
 
 Docusaurus [went live](https://v1.docusaurus.io/blog/2017/12/14/introducing-docusaurus) on December 14, 2017. At the time, we had [8 early adopters](https://v1.docusaurus.io/blog/2017/12/14/introducing-docusaurus#acknowledgements).
 

website/blog/2020-01-07-tribute-to-endi.md

@@ -20,4 +20,4 @@ We are working on ways to honor Endi's contributions - a commemorative sticker,
 
 The Docusaurus project will not be the same without Endi, and those of us who worked with him will miss him greatly. 😔
 
-![Endi](/img/endi.jpg)
+![A photo from behind Endi's back, with Endi sitting on a rock cliff, facing the vast sea. His right hand forms a V pose.](/img/endi.jpg)

website/blog/2021-01-19-docusaurus-2020-recap.md

@@ -13,7 +13,7 @@ We now **recommend Docusaurus 2** as the **default choice** to start a new Docus
 
 We are **still in alpha**, but expect **some good news very soon**!
 
-![Docusaurus v1 vs v2 npm trends](/img/blog/2020-recap/docusaurus-plushie-banner.jpeg)
+![Three Docusaurus plushies laid side-by-side on the table](/img/blog/2020-recap/docusaurus-plushie-banner.jpeg)
 
 <!--truncate-->
 
@@ -40,7 +40,7 @@ We have worked on many features this year, and would like to highlight the most
 
 The plan to [rebuild Docusaurus from scratch in 2019](https://docusaurus.io/blog/2019/12/30/docusaurus-2019-recap) paid off: after a slow start, Docusaurus 2 has been widely adopted and has **already outgrown Docusaurus 1** usage.
 
-![Docusaurus v1 vs v2 npm trends](/img/blog/2020-recap/docusaurus-npm-trends.png)
+![Docusaurus v1 vs. v2 npm trends of the year 2020. The installations of Docusaurus v2 is visibly up-growing, while v1 is slightly downward. V1 starts at 15000 and ends at 10000, while v2 starts at 2000 and ends at 25000. The intersection happens around June 2020.](/img/blog/2020-recap/docusaurus-npm-trends.png)
 
 Notable **projects, startups, large companies, and individuals** adopted Docusaurus 2 ([showcase](https://docusaurus.io/showcase)):
 
@@ -57,15 +57,15 @@ We helped **large scale Docusaurus 1 sites to upgrade**, ensuring a proper **mig
 
 [React Native](https://reactnative.dev/) was successfully upgraded to Docusaurus 2 ([archived v1 site](http://archive.reactnative.dev/)):
 
-![React Native screenshot](/img/blog/2020-recap/react-native-screenshot.png)
+![React Native's new website built with Docusaurus v2](/img/blog/2020-recap/react-native-screenshot.png)
 
 Localized Docusaurus 1 sites (like **Jest**) will be able to upgrade too:
 
-![Jest in Japanese screenshot](/img/blog/2020-recap/jest-screenshot.png)
+![Jest's new website built with Docusaurus v2 in Japanese](/img/blog/2020-recap/jest-screenshot.png)
 
 We also saw the **[first right-to-left](https://datagit.ir/)** Docusaurus 2 site published:
 
-![Datagit screenshot](/img/blog/2020-recap/datagit-rtl-screenshot.png)
+![Datagit's website in Persian, a right-to-left language. The sidebar appears on the right of the window and the TOC appears on the left.](/img/blog/2020-recap/datagit-rtl-screenshot.png)
 
 ## GitHub Activity
 

website/blog/2021-03-09-releasing-docusaurus-i18n.md

@@ -58,23 +58,23 @@ We have made it possible to **upgrade** a **translated Docusaurus 1 site** to Do
 
 The Docusaurus 2 migration was successful and the new site is now deployed in production ([announcement post](https://jestjs.io/blog/2021/03/09/jest-website-upgrade)).
 
-[![Jest i18n screenshot](/img/blog/2021-03-09-releasing-docusaurus-i18n/jest.png)](https://jestjs.io)
+[![Jest's website front page in Japanese](/img/blog/2021-03-09-releasing-docusaurus-i18n/jest.png)](https://jestjs.io)
 
 ### Redwood: adopting Docusaurus
 
 [Redwood](https://redwoodjs.com/) is a React full-stack Jamstack framework.
 
 They were looking for a solution to create an **internationalized learning platform**, and became early adopters of Docusaurus 2 i18n for [learn.redwoodjs.com](https://learn.redwoodjs.com/), using Crowdin to get it translated to French.
 
-[![Redwood i18n screenshot](/img/blog/2021-03-09-releasing-docusaurus-i18n/redwood.png)](https://learn.redwoodjs.com/)
+[![Redwood's doc page in French](/img/blog/2021-03-09-releasing-docusaurus-i18n/redwood.png)](https://learn.redwoodjs.com/)
 
 ### Datagit: using LTR support
 
 The i18n system should work with any language, including **Right-to-Left languages**.
 
 [Datagit.ir](https://datagit.ir/) is using Farsi, and a simple configuration option is able to **flip the Docusaurus theme** to add the required Right-to-Left support.
 
-[![Datagit i18n screenshot](/img/blog/2021-03-09-releasing-docusaurus-i18n/datagit.png)](https://datagit.ir/)
+[![Datagit's website in Persian, a right-to-left language. The sidebar appears on the right of the window and the TOC appears on the left.](/img/blog/2021-03-09-releasing-docusaurus-i18n/datagit.png)](https://datagit.ir/)
 
 ## Conclusion
 

website/blog/2021-05-12-announcing-docusaurus-two-beta/index.md

@@ -15,7 +15,7 @@ After a lengthy alpha stage in order to ensure feature parity and quality, we ar
 
 With the announcement of this beta, the team is even more confident that Docusaurus 2 is **ready for mainstream adoption**!
 
-![Docusaurus beta party](./img/image_cropped.png)
+![](./img/image_cropped.png)
 
 <!--truncate-->
 
@@ -25,13 +25,13 @@ With the announcement of this beta, the team is even more confident that Docusau
 
 Docusaurus 2 is widely adopted and growing fast:
 
-[![Docusaurus growth](./img/trend.png)](https://www.npmtrends.com/docusaurus-vs-@docusaurus/core)
+[![Docusaurus v1 vs. v2 npm trends from 2019 to mid 2021. The installations of Docusaurus v2 is sharply rising, while v1 is mostly stable. V1 fluctuates between 10000 and 20000, while v2 starts at 0 and ends at almost 60000. The intersection happens around June 2020.](./img/trend.png)](https://www.npmtrends.com/docusaurus-vs-@docusaurus/core)
 
 To get a fuller understanding of the quality of current Docusaurus 2 sites, our new [showcase](https://docusaurus.io/showcase) page allows you to filter Docusaurus sites by features, so you may get inspired by real-world production sites with a similar use-case as yours!
 
 Don't miss our [favorite](https://docusaurus.io/showcase?tags=favorite) sites; they all stand out with something unique:
 
-[![Docusaurus growth](./img/favorites.png)](https://docusaurus.io/showcase?tags=favorite)
+[![A screenshot of the showcase's favorites section, with 12 cards each displaying the information and preview of one site](./img/favorites.png)](https://docusaurus.io/showcase?tags=favorite)
 
 ## Why was Docusaurus v2 in alpha for so long?
 

website/blog/2021-11-21-algolia-docsearch-migration/index.md

@@ -74,19 +74,19 @@ DocSearch now leverages the [Algolia Crawler](https://www.algolia.com/products/s
 - Edit your config file from a live editor
 - Test your results with DocSearch v3
 
-![Algolia crawler overview](./img/crawler-overview.png)
+![The Algolia crawler front page showing the project's overview, such as last complete crawl and indices](./img/crawler-overview.png)
 
-![Algolia config editor](./img/editor.png)
+![The Algolia config editor opened to the docusaurus-2 config. The right pane shows the results for index and various facet filters.](./img/editor.png)
 
 But also, more Algolia features in **your own Algolia app**:
 
 - Team management
 - Browse and see how your records are indexed in Algolia
 - Try other Algolia features with free trials
 
-![Algolia index overview](./img/index-overview.png)
+![The Algolia index overview page, showing various filters and the details of every single index](./img/index-overview.png)
 
-![Algolia index analytics](./img/index-analytics.png)
+![The Algolia index analytics page, showing trends for total users, total searches, etc.](./img/index-analytics.png)
 
 And of course, **a lot more, for free**.