Deploy website

Deploy website version based on 9ef4d7d8bf
2025-08-04 17:28:57 +02:00 · 2018-04-28 05:55:52 +00:00 · 2018-04-28 05:55:52 +00:00 · 8b9f82c487
commit 8b9f82c487
parent 9ef4d7d8bf
19 changed files with 330 additions and 298 deletions
--- a/blog/2017/12/14/introducing-docusaurus.html
+++ b/blog/2017/12/14/introducing-docusaurus.html
@ -20,53 +20,53 @@
 <p><img src="/img/slash-birth.png" alt="Birth of Slash"></p>
 <p>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.</p>
 <p>The open source team tried to help mitigate this problem by coming up with a standard template, based on Jekyll, that could be used as a starting point for a project website. We asked our new projects to manually copy our template source to  their repo, write their docs, and publish. This template approach was adopted by most of open source projects launched; some existing projects even converted their custom website implementations to the new template as well.</p>
-<p>The problem with the “copy the template to your repo” approach is that, even though the platform is consistent, pushing updates becomes unmaintainable across an entire suite of projects already using the template. This is because we lost control of the template after a project copied it to their repo. Projects were free to modify the template as desired and apply their own project-specific features to it. So while projects share the same site generation platform, they have now diverted enough where they cannot take advantage of the new features we have added to the template over time. There was no easy way we could ask all current projects to “copy” a new version of the template since it might break their existing site or remove features that they have added on their own. Instead, we would have to apply the updates manually to each project one-by-one. This became very problematic when projects started asking for our team for internationalization support within the template, requiring low-level changes to how the template was structured and generated.</p>
+<p>The problem with the &quot;copy the template to your repo&quot; approach is that, even though the platform is consistent, pushing updates becomes unmaintainable across an entire suite of projects already using the template. This is because we lost control of the template after a project copied it to their repo. Projects were free to modify the template as desired and apply their own project-specific features to it. So while projects share the same site generation platform, they have now diverted enough where they cannot take advantage of the new features we have added to the template over time. There was no easy way we could ask all current projects to &quot;copy&quot; a new version of the template since it might break their existing site or remove features that they have added on their own. Instead, we would have to apply the updates manually to each project one-by-one. This became very problematic when projects started asking for our team for internationalization support within the template, requiring low-level changes to how the template was structured and generated.</p>
 <p>So we started thinking about what we could do to help mitigate the challenge of keeping sites updated and consistent across our entire portfolio. We also wanted multiple projects to share the same site generation software. We wanted them to start out with the same template, and yet have the flexibility to customize and adapt their site theme to suit their needs. They should be able to extend and customize their site, but when we update the underlying infrastructure with fixes and features, the project should be able update simply and without any breaking changes.</p>
 <p>Docusaurus was born!</p>
 <p>At Facebook, Docusaurus allows us to quickly get different projects up and running with documentation websites, especially for teams who don't have much experience with web development or primarily want a basic site to showcase their project. Docusaurus already supports sites needing more advanced features like internationalization for Jest and versioning for React Native. As different projects request new features for their sites, they are added to Docusaurus and simultaneously provided to all projects! All together, this ends up greatly reducing the work needed  to maintain different sites for different projects. Our teams are able to focus on keeping their projects healthier by spending more time adding features, fixing bugs, and writing documentation.</p>
 <h2><a class="anchor" aria-hidden="true" id="getting-up-and-running"></a><a href="#getting-up-and-running" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Getting Up and Running</h2>
 <p><img src="/img/slash-upandrunning.png" alt="Slash Up and Running"></p>
 <p>At its core, we wanted sites running Docusaurus to be simple to use. With one <a href="https://docusaurus.io/docs/en/installation.html">installation</a> command and some simple <a href="https://docusaurus.io/docs/en/site-preparation.html">configuration</a>, you can actually have a default running website.</p>
-<p>When you run docusaurus-init, you will see a structure similar to:</p>
-<pre><code class="hljs">root-of-repo
+<p>When you run <code>docusaurus-init</code>, you will see a structure similar to:</p>
+<pre><code class="hljs css bash">root-of-repo
 ├── docs-examples-from-docusaurus
-│   ├── doc1<span class="hljs-selector-class">.md</span>
-│   ├── doc2<span class="hljs-selector-class">.md</span>
-│   ├── doc3<span class="hljs-selector-class">.md</span>
-│   ├── exampledoc4<span class="hljs-selector-class">.md</span>
-│   └── exampledoc5<span class="hljs-selector-class">.md</span>
+│   ├── doc1.md
+│   ├── doc2.md
+│   ├── doc3.md
+│   ├── exampledoc4.md
+│   └── exampledoc5.md
 ├── website
 │   ├── blog-examples-from-docusaurus
-│   │   ├── <span class="hljs-number">2016</span>-<span class="hljs-number">03</span>-<span class="hljs-number">11</span>-blog-post<span class="hljs-selector-class">.md</span>
-│   │   └── <span class="hljs-number">2017</span>-<span class="hljs-number">04</span>-<span class="hljs-number">10</span>-blog-post-two<span class="hljs-selector-class">.md</span>
+│   │   ├── 2016-03-11-blog-post.md
+│   │   └── 2017-04-10-blog-post-two.md
 │   ├── core
-│   │   └── Footer<span class="hljs-selector-class">.js</span>
+│   │   └── Footer.js
 │   ├── node_modules
-│   ├── package<span class="hljs-selector-class">.json</span>
+│   ├── package.json
 │   ├── pages
-│   ├── sidebars<span class="hljs-selector-class">.json</span>
-│   ├── siteConfig<span class="hljs-selector-class">.js</span>
+│   ├── sidebars.json
+│   ├── siteConfig.js
 │   └── static
 </code></pre>
-<p>With the exception of node_modules and package.json, all the directories and files you see are where you customize and add content to your Docusaurus-based website. The docs folder is where you add your markdown that represents your documentation; the blog folder is where you add your markdown for your <a href="https://docusaurus.io/docs/en/blog.html">blog posts</a>; siteConfig.js is where you make most of the <a href="https://docusaurus.io/docs/en/site-config.html">customizations</a> for your site; sidebars.json is where you maintain the layout and content of the <a href="https://docusaurus.io/docs/en/navigation.html">sidebar</a> for your documentation; the pages folder is where you add <a href="https://docusaurus.io/docs/en/custom-pages.html">custom</a> pages for your site; the static folder is where all of your static assets go (e.g., css stylesheets and images); and the core folder is where you can customize core components of the site, in this case the footer.</p>
+<p>With the exception of node_modules and package.json, all the directories and files you see are where you customize and add content to your Docusaurus-based website. The docs folder is where you add your markdown that represents your documentation; the blog folder is where you add your markdown for your <a href="https://docusaurus.io/docs/en/blog.html">blog posts</a>; <code>siteConfig.js</code> is where you make most of the <a href="https://docusaurus.io/docs/en/site-config.html">customizations</a> for your site; <code>sidebars.json</code> is where you maintain the layout and content of the <a href="https://docusaurus.io/docs/en/navigation.html">sidebar</a> for your documentation; the <code>pages</code> folder is where you add <a href="https://docusaurus.io/docs/en/custom-pages.html">custom</a> pages for your site; the <code>static</code> folder is where all of your static assets go (e.g., CSS stylesheets and images); and the <code>core</code> folder is where you can customize core components of the site, in this case the footer.</p>
 <h2><a class="anchor" aria-hidden="true" id="how-does-docusaurus-work"></a><a href="#how-does-docusaurus-work" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>How does Docusaurus work?</h2>
-<p>Docusaurus is written primarily in JavaScript and <a href="https://facebook.github.io/react">React</a>, replacing the Jekyll we had in the old template. We use <a href="https://github.com/jonschlinkert/remarkable">Remarkable</a> for our markdown rendering and <a href="https://highlightjs.org/">highlight.js</a> for our code block syntax highlighting. The core of Docusaurus' functionality is in the <a href="https://github.com/facebookexperimental/Docusaurus/tree/master/lib">lib directory</a> of the <a href="https://github.com/facebookexperimental/Docusaurus/">Docusaurus repo</a>. The general structure looks like:</p>
-<pre><code class="hljs">root-of-Docusaurus
+<p>Docusaurus is written primarily in JavaScript and <a href="https://facebook.github.io/react">React</a>, replacing Jekyll which we used in the old template. We use <a href="https://github.com/jonschlinkert/remarkable">Remarkable</a> for our markdown rendering and <a href="https://highlightjs.org/">highlight.js</a> for our code block syntax highlighting. The core of Docusaurus' functionality is in the <a href="https://github.com/facebookexperimental/Docusaurus/tree/master/lib">lib directory</a> of the <a href="https://github.com/facebook/Docusaurus/">Docusaurus repo</a>. The general structure looks like:</p>
+<pre><code class="hljs css bash">root-of-Docusaurus
 ├── lib
 │   ├── core
 │   ├── server
-│   │   ├── generate<span class="hljs-selector-class">.js</span>
-│   │   ├── server<span class="hljs-selector-class">.js</span>
-│   │   └── ..<span class="hljs-selector-class">.and</span> more files
+│   │   ├── generate.js
+│   │   ├── server.js
+│   │   └── ...and more files
 │   ├── static
-│   ├── build-files<span class="hljs-selector-class">.js</span>
-│   ├── copy-examples<span class="hljs-selector-class">.js</span>
-│   ├── generate-feed<span class="hljs-selector-class">.js</span>
-│   ├── publish-gh-pages<span class="hljs-selector-class">.js</span>
-│   ├── rename-version<span class="hljs-selector-class">.js</span>
-│   ├── start-server<span class="hljs-selector-class">.js</span>
-│   ├── versions<span class="hljs-selector-class">.js</span>
-│   └── write-translations<span class="hljs-selector-class">.js</span>
+│   ├── build-files.js
+│   ├── copy-examples.js
+│   ├── generate-feed.js
+│   ├── publish-gh-pages.js
+│   ├── rename-version.js
+│   ├── start-server.js
+│   ├── versions.js
+│   └── write-translations.js
 </code></pre>
 <p>The key files here are build-files.js and start-server.js. There are many similarities between these two files: <code>build-files.js</code> is used to build the physical artifacts for serving by an external web server. <code>start-server.js</code> is used  to run the Docusaurus server and locally test your site. Both go through the following general process to take all of the markdown and configuration to create a runnable website:</p>
 <ol>
@ -84,19 +84,19 @@
 </ol>
 <p>Note that this process does not take into full account how translations or versioning works. The underlying details of those features will be saved for future blog posts.</p>
 <p>The final structure of your compiled site will look similar to:</p>
-<pre><code class="hljs">build
+<pre><code class="hljs css bash">build
 ├── website
 │   ├── CNAME
 │   ├── blog
 │   ├── css
 │   ├── docs
 │   ├── en
-│   ├── help.html # custom<span class="hljs-built_in"> page
-</span>│   ├── img
-│   ├── index.html # landing<span class="hljs-built_in"> page
-</span>│   ├── sitemap.xml
-│   └── users.html # custom<span class="hljs-built_in"> page
-</span></code></pre>
+│   ├── help.html <span class="hljs-comment"># custom page</span>
+│   ├── img
+│   ├── index.html <span class="hljs-comment"># landing page</span>
+│   ├── sitemap.xml
+│   └── users.html <span class="hljs-comment"># custom page</span>
+</code></pre>
 <h2><a class="anchor" aria-hidden="true" id="community"></a><a href="#community" aria-hidden="true" class="hash-link" ><svg aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Community</h2>
 <p><img src="/img/docusaurus.svg" alt="Docusaurus"></p>
 <p>We welcome your <a href="https://github.com/facebook/Docusaurus/blob/master/CONTRIBUTING.md">contributions</a> to Docusaurus, whether you want to use it for your own site, you want to <a href="https://github.com/facebook/Docusaurus/blob/master/CONTRIBUTING.md">contribute</a> to the Docusaurus core or just have questions. Follow us on <a href="https://github.com/facebook/Docusaurus">GitHub</a> and <a href="https://twitter.com/docusaurus">Twitter</a>.</p>