mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-21 04:57:05 +02:00
docs: improve alt messages (#8047)
This commit is contained in:
Joshua Chen
GitHub
parent
1f1f898d73
commit
36db64ed1d
22 changed files with 76 additions and 72 deletions
|
|
@ -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:
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ authors: JMarcey
|
|||
tags: [documentation, blog, docusaurus]
|
||||
---
|
||||
|
||||
|
||||
|
||||
|
||||
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
|
||||
|
||||
|
||||
|
||||
|
||||
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
|
||||
|
||||
|
||||
|
||||
|
||||
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
|
||||
|
||||
|
||||
|
||||
|
||||
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).
|
||||
|
||||
|
|
|
|||
|
|
@ -48,37 +48,41 @@ Here's an overview of the steps taken to convert to a website. I'll discuss some
|
|||
|
||||
1. Added metadata to the existing Markdown files found in the `docs` folder, for example:
|
||||
|
||||
+---
|
||||
+id: architecture
|
||||
+title: Architecture
|
||||
+sidebar_label: Architecture
|
||||
+---
|
||||
```md
|
||||
---
|
||||
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.)
|
||||
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:
|
||||
|
||||
```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.
|
||||
|
||||
|
|
@ -86,15 +90,15 @@ The final website was published on https://facebookincubator.github.io/profilo/.
|
|||
|
||||
Here's what the initial website looked like when the first pull request was sent out:
|
||||
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
|
||||
The selected primary and secondary colors were a good jumping off point for designer feedback.
|
||||
|
||||
|
|
@ -102,17 +106,17 @@ There were also modifications made to the default website generated by Docusauru
|
|||
|
||||
Here's what the final website looked like:
|
||||
|
||||
|
||||
|
||||
|
||||
This is an example page showing the core content, in this case the Getting Started page:
|
||||
|
||||
|
||||
|
||||
|
||||
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!
|
||||
|
||||
|
||||
|
||||
|
||||
## Final Thoughts
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ authors:
|
|||
tags: [birth]
|
||||
---
|
||||
|
||||
|
||||
|
||||
|
||||
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).
|
||||
|
||||
|
|
|
|||
|
|
@ -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. 😔
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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**!
|
||||
|
||||
|
||||
|
||||
|
||||
<!--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.
|
||||
|
||||
|
||||
|
||||
|
||||
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/)):
|
||||
|
||||
|
||||
|
||||
|
||||
Localized Docusaurus 1 sites (like **Jest**) will be able to upgrade too:
|
||||
|
||||
|
||||
|
||||
|
||||
We also saw the **[first right-to-left](https://datagit.ir/)** Docusaurus 2 site published:
|
||||
|
||||
|
||||
|
||||
|
||||
## GitHub Activity
|
||||
|
||||
|
|
|
|||
|
|
@ -58,7 +58,7 @@ 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)).
|
||||
|
||||
[](https://jestjs.io)
|
||||
[](https://jestjs.io)
|
||||
|
||||
### Redwood: adopting Docusaurus
|
||||
|
||||
|
|
@ -66,7 +66,7 @@ The Docusaurus 2 migration was successful and the new site is now deployed in pr
|
|||
|
||||
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.
|
||||
|
||||
[](https://learn.redwoodjs.com/)
|
||||
[](https://learn.redwoodjs.com/)
|
||||
|
||||
### Datagit: using LTR support
|
||||
|
||||
|
|
@ -74,7 +74,7 @@ The i18n system should work with any language, including **Right-to-Left languag
|
|||
|
||||
[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.
|
||||
|
||||
[](https://datagit.ir/)
|
||||
[](https://datagit.ir/)
|
||||
|
||||
## Conclusion
|
||||
|
||||
|
|
|
|||
|
|
@ -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**!
|
||||
|
||||
|
||||
|
||||
|
||||
<!--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:
|
||||
|
||||
[](https://www.npmtrends.com/docusaurus-vs-@docusaurus/core)
|
||||
[](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:
|
||||
|
||||
[](https://docusaurus.io/showcase?tags=favorite)
|
||||
[](https://docusaurus.io/showcase?tags=favorite)
|
||||
|
||||
## Why was Docusaurus v2 in alpha for so long?
|
||||
|
||||
|
|
|
|||
|
|
@ -74,9 +74,9 @@ 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
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
But also, more Algolia features in **your own Algolia app**:
|
||||
|
||||
|
|
@ -84,9 +84,9 @@ But also, more Algolia features in **your own Algolia app**:
|
|||
- Browse and see how your records are indexed in Algolia
|
||||
- Try other Algolia features with free trials
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
And of course, **a lot more, for free**.
|
||||
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ We've **reached full feature parity** with v1 after [the release of internationa
|
|||
|
||||
The **official v2 release** is just around the corner! Follow the [roadmap issue](https://github.com/facebook/docusaurus/issues/6113) for any latest news.
|
||||
|
||||
|
||||
|
||||
|
||||
<!--truncate-->
|
||||
|
||||
|
|
@ -38,7 +38,7 @@ Our codebase has been polished over time as well. We have improved test coverage
|
|||
|
||||
Docusaurus v2 continues to grow steadily. V2 installation is now 8 times more than v1. In terms of weekly downloads, we have witnessed another three-fold increase (+209.4%), growing from 28,066 in early January to a peak of 86,846 in mid-December.
|
||||
|
||||
[](https://www.npmtrends.com/docusaurus-vs-@docusaurus/core)
|
||||
[](https://www.npmtrends.com/docusaurus-vs-@docusaurus/core)
|
||||
|
||||
(Ah, the classic Christmas dip...)
|
||||
|
||||
|
|
@ -55,11 +55,11 @@ We released 18 versions, going from `2.0.0-alpha.71` to `2.0.0-beta.14`. That's
|
|||
|
||||
Our star trend is also very positive. Compared to similar projects, we are **growing at a faster rate**:
|
||||
|
||||
|
||||
|
||||
|
||||
With an 8.4k increase in stars, we are ranked number 3 in this year's [JavaScript rising stars of static site generators](https://risingstars.js.org/2021/en#section-ssg), preceded only by Next.js and Astro.
|
||||
|
||||
|
||||
|
||||
|
||||
## Featured adoptions
|
||||
|
||||
|
|
@ -67,15 +67,15 @@ Our showcase has welcomed a few new ["favorite" sites](/showcase?tags=favorite)
|
|||
|
||||
- [**IOTA-wiki**](https://wiki.iota.org/)
|
||||
|
||||
|
||||
|
||||
|
||||
- [**Dyte**](https://docs.dyte.io/docs/home/introduction/)
|
||||
|
||||
|
||||
|
||||
|
||||
- [**Ionic**](https://ionicframework.com/docs)
|
||||
|
||||
|
||||
|
||||
|
||||
- [**Courier**](https://www.courier.com/docs/)
|
||||
|
||||
|
|
|
|||
|
|
@ -563,7 +563,7 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
:::caution
|
||||
|
||||
|
|
|
|||
|
|
@ -66,4 +66,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:
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -66,7 +66,7 @@ For a more exhaustive list of what it takes for your site to be a PWA, refer to
|
|||
|
||||
If your browser supports it, you should be able to install a Docusaurus site as an app.
|
||||
|
||||
|
||||
|
||||
|
||||
:::note
|
||||
|
||||
|
|
@ -298,6 +298,6 @@ The `@theme/PwaReloadPopup` component is rendered when a new service worker is w
|
|||
|
||||
The default theme includes an implementation for the reload popup and uses [Infima Alerts](https://infima.dev/docs/components/alert).
|
||||
|
||||
|
||||
|
||||
|
||||
Your component can render `null`, but this is not recommended: users won't have a way to get up-to-date content.
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ slug: /
|
|||
|
||||
🧐 Docusaurus is a **static-site generator**. It builds a **single-page application** with fast client-side navigation, leveraging the full power of **React** to make your site interactive. It provides out-of-the-box **documentation features** but can be used to create **any kind of site** (personal website, product, blog, marketing landing pages, etc).
|
||||
|
||||
|
||||
|
||||
|
||||
## Fast Track ⏱️ {#fast-track}
|
||||
|
||||
|
|
|
|||
|
|
@ -567,7 +567,7 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
:::caution
|
||||
|
||||
|
|
|
|||
|
|
@ -66,4 +66,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:
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -66,7 +66,7 @@ For a more exhaustive list of what it takes for your site to be a PWA, refer to
|
|||
|
||||
If your browser supports it, you should be able to install a Docusaurus site as an app.
|
||||
|
||||
|
||||
|
||||
|
||||
:::note
|
||||
|
||||
|
|
@ -298,6 +298,6 @@ The `@theme/PwaReloadPopup` component is rendered when a new service worker is w
|
|||
|
||||
The default theme includes an implementation for the reload popup and uses [Infima Alerts](https://infima.dev/docs/components/alert).
|
||||
|
||||
|
||||
|
||||
|
||||
Your component can render `null`, but this is not recommended: users won't have a way to get up-to-date content.
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ slug: /
|
|||
|
||||
🧐 Docusaurus is a **static-site generator**. It builds a **single-page application** with fast client-side navigation, leveraging the full power of **React** to make your site interactive. It provides out-of-the-box **documentation features** but can be used to create **any kind of site** (personal website, product, blog, marketing landing pages, etc).
|
||||
|
||||
|
||||
|
||||
|
||||
## Fast Track ⏱️ {#fast-track}
|
||||
|
||||
|
|
|
|||
|
|
@ -563,7 +563,7 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
:::caution
|
||||
|
||||
|
|
|
|||
|
|
@ -66,4 +66,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:
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -66,7 +66,7 @@ For a more exhaustive list of what it takes for your site to be a PWA, refer to
|
|||
|
||||
If your browser supports it, you should be able to install a Docusaurus site as an app.
|
||||
|
||||
|
||||
|
||||
|
||||
:::note
|
||||
|
||||
|
|
@ -298,6 +298,6 @@ The `@theme/PwaReloadPopup` component is rendered when a new service worker is w
|
|||
|
||||
The default theme includes an implementation for the reload popup and uses [Infima Alerts](https://infima.dev/docs/components/alert).
|
||||
|
||||
|
||||
|
||||
|
||||
Your component can render `null`, but this is not recommended: users won't have a way to get up-to-date content.
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ slug: /
|
|||
|
||||
🧐 Docusaurus is a **static-site generator**. It builds a **single-page application** with fast client-side navigation, leveraging the full power of **React** to make your site interactive. It provides out-of-the-box **documentation features** but can be used to create **any kind of site** (personal website, product, blog, marketing landing pages, etc).
|
||||
|
||||
|
||||
|
||||
|
||||
## Fast Track ⏱️ {#fast-track}
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue