mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-04 01:09:20 +02:00
Website Deployment Script
parent
62021fdee3
commit
2e30a5e804
26 changed files with 52 additions and 50 deletions
|
|
@ -1,10 +1,10 @@
|
|||
<html lang="en"><head><meta charset="utf-8"/><meta http-equiv="X-UA-Compatible" content="IE=edge"/><title>Introducing Docusaurus · Docusaurus</title><meta name="viewport" content="width=device-width"/><meta name="generator" content="Docusaurus"/><meta property="og:title" content="Introducing Docusaurus · Docusaurus"/><meta property="og:type" content="website"/><meta property="og:url" content="https://docusaurus.io/blog/2017/12/14/introducing-docusaurus.html"/><meta property="og:description" content="We are very happy to introduce [Docusaurus](https://github.com/facebook/Docusaurus) to help you manage one or many open source websites."/><meta property="og:image" content="https://docusaurus.io/img/docusaurus.png"/><link rel="shortcut icon" href="/img/docusaurus.ico"/><link rel="stylesheet" href="https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.css"/><link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/solarized-dark.min.css"/><link rel="alternate" type="application/atom+xml" href="https://docusaurus.io/blog/atom.xml" title="Docusaurus Blog ATOM Feed"/><link rel="alternate" type="application/rss+xml" href="https://docusaurus.io/blog/feed.xml" title="Docusaurus Blog RSS Feed"/><script type="text/javascript" src="https://buttons.github.io/buttons.js"></script><link rel="stylesheet" href="/css/main.css"/></head><body class="sideNavVisible separateOnPageNav"><div class="fixedHeaderContainer"><div class="headerWrapper wrapper"><header><a href="/en"><img class="logo" src="/img/docusaurus.svg"/><h2 class="headerTitle">Docusaurus</h2></a><div class="navigationWrapper navigationSlider"><nav class="slidingNav"><ul class="nav-site nav-site-internal"><li class=""><a href="/docs/en/installation.html" target="_self">Docs</a></li><li class=""><a href="/en/help.html" target="_self">Help</a></li><li class=""><a href="/en/about-slash.html" target="_self">About /</a></li><li class="siteNavGroupActive"><a href="/blog" target="_self">Blog</a></li><li class=""><a href="https://github.com/facebook/docusaurus" target="_self">GitHub</a></li><li class="navSearchWrapper reactNavSearchWrapper"><input type="text" id="search_input_react" placeholder="Search"/></li></ul></nav></div></header></div></div><div class="navPusher"><div class="docMainWrapper wrapper"><div class="container docsNavContainer" id="docsNav"><nav class="toc"><div class="toggleNav"><section class="navWrapper wrapper"><div class="navBreadcrumb wrapper"><div class="navToggle" id="navToggler"><i></i></div><h2><i>›</i><span>Recent Posts</span></h2></div><div class="navGroups"><div class="navGroup navGroupActive"><h3>Recent Posts</h3><ul><li class="navListItem navListItemActive"><a class="navItem navItemActive" href="/blog/2017/12/14/introducing-docusaurus.html">Introducing Docusaurus</a></li></ul></div></div></section></div><script>
|
||||
<html lang="en"><head><meta charset="utf-8"/><meta http-equiv="X-UA-Compatible" content="IE=edge"/><title>Introducing Docusaurus · Docusaurus</title><meta name="viewport" content="width=device-width"/><meta name="generator" content="Docusaurus"/><meta property="og:title" content="Introducing Docusaurus · Docusaurus"/><meta property="og:type" content="website"/><meta property="og:url" content="https://docusaurus.io/blog/2017/12/14/introducing-docusaurus.html"/><meta property="og:description" content="We are very happy to introduce [Docusaurus](https://github.com/facebook/Docusaurus) to help you manage one or many open source websites."/><meta property="og:image" content="https://docusaurus.io/img/docusaurus.png"/><link rel="shortcut icon" href="/img/docusaurus.ico"/><link rel="stylesheet" href="https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.css"/><link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/solarized-dark.min.css"/><link rel="alternate" type="application/atom+xml" href="https://docusaurus.io/blog/atom.xml" title="Docusaurus Blog ATOM Feed"/><link rel="alternate" type="application/rss+xml" href="https://docusaurus.io/blog/feed.xml" title="Docusaurus Blog RSS Feed"/><script type="text/javascript" src="https://buttons.github.io/buttons.js"></script><link rel="stylesheet" href="/css/main.css"/></head><body class="sideNavVisible separateOnPageNav"><div class="fixedHeaderContainer"><div class="headerWrapper wrapper"><header><a href="/en"><img class="logo" src="/img/docusaurus.svg" alt="Docusaurus"/><h2 class="headerTitle">Docusaurus</h2></a><div class="navigationWrapper navigationSlider"><nav class="slidingNav"><ul class="nav-site nav-site-internal"><li class=""><a href="/docs/en/installation.html" target="_self">Docs</a></li><li class=""><a href="/en/help.html" target="_self">Help</a></li><li class=""><a href="/en/about-slash.html" target="_self">About /</a></li><li class="siteNavGroupActive"><a href="/blog" target="_self">Blog</a></li><li class=""><a href="https://github.com/facebook/docusaurus" target="_self">GitHub</a></li><li class="navSearchWrapper reactNavSearchWrapper"><input type="text" id="search_input_react" placeholder="Search"/></li></ul></nav></div></header></div></div><div class="navPusher"><div class="docMainWrapper wrapper"><div class="container docsNavContainer" id="docsNav"><nav class="toc"><div class="toggleNav"><section class="navWrapper wrapper"><div class="navBreadcrumb wrapper"><div class="navToggle" id="navToggler"><i></i></div><h2><i>›</i><span>Recent Posts</span></h2></div><div class="navGroups"><div class="navGroup navGroupActive"><h3>Recent Posts</h3><ul><li class="navListItem navListItemActive"><a class="navItem navItemActive" href="/blog/2017/12/14/introducing-docusaurus.html">Introducing Docusaurus</a></li></ul></div></div></section></div><script>
|
||||
var toggler = document.getElementById('navToggler');
|
||||
var nav = document.getElementById('docsNav');
|
||||
toggler.onclick = function() {
|
||||
nav.classList.toggle('docsSliderActive');
|
||||
};
|
||||
</script></nav></div><div class="container mainContainer documentContainer postContainer blogContainer"><div class="wrapper"><div class="lonePost"><div class="post"><header class="postHeader"><h1><a href="/blog/2017/12/14/introducing-docusaurus.html">Introducing Docusaurus</a></h1><p class="post-meta">December 14, 2017</p><div class="authorBlock"><p class="post-authorName"><a href="http://twitter.com/JoelMarcey" target="_blank">Joel Marcey</a></p><div class="authorPhoto"><a href="http://twitter.com/JoelMarcey" target="_blank"><img src="https://graph.facebook.com/611217057/picture/?height=200&width=200"/></a></div></div></header><div><span><p><img src="/img/slash-introducing.png" alt=""></p>
|
||||
</script></nav></div><div class="container mainContainer documentContainer postContainer blogContainer"><div class="wrapper"><div class="lonePost"><div class="post"><header class="postHeader"><h1><a href="/blog/2017/12/14/introducing-docusaurus.html">Introducing Docusaurus</a></h1><p class="post-meta">December 14, 2017</p><div class="authorBlock"><p class="post-authorName"><a href="http://twitter.com/JoelMarcey" target="_blank">Joel Marcey</a></p><div class="authorPhoto"><a href="http://twitter.com/JoelMarcey" target="_blank"><img src="https://graph.facebook.com/611217057/picture/?height=200&width=200" alt="Joel Marcey"/></a></div></div></header><div><span><p><img src="/img/slash-introducing.png" alt="Introducing Slash"></p>
|
||||
<p>We are very happy to introduce <a href="https://github.com/facebook/Docusaurus">Docusaurus</a> to help you manage one or many open source websites.</p>
|
||||
<p>We created <a href="https://docusaurus.io">Docusaurus</a> for the following reasons:</p>
|
||||
<ol>
|
||||
|
|
@ -17,7 +17,7 @@
|
|||
<p>Docusaurus is a tool designed to make it easy for teams to publish documentation websites without having to worry about the infrastructure and design details. At its core, all a user has to provide are documentation files written in markdown, customization of a provided home page written in React, and a few configuration modifications. Docusaurus handles the rest by providing default styles, site formatting, and simple document navigation. Getting started is easy, as users can <a href="https://docusaurus.io/docs/en/installation.html">install</a> it using <code>npm</code> or <code>yarn</code> via a simple initialization script that <a href="https://docusaurus.io/docs/en/site-preparation.html">creates a working example website out of the box</a>.</p>
|
||||
<p>Docusaurus also provides core website and documentation features out-of-the-box including <a href="https://docusaurus.io/docs/en/blog.html">blog support</a>, <a href="https://docusaurus.io/docs/en/translation.html">internationalization</a>, <a href="https://docusaurus.io/docs/en/search.html">search</a>, and <a href="https://docusaurus.io/docs/en/versioning.html">versioning</a>. While some projects may not require any of these features, enabling them is generally a matter of updating configuration options instead of having to add the infrastructure from the ground up. As more features get added to Docusaurus, users just can easily update to the latest version. This can be done by simply running npm or yarn update and updating configuration options. Users or teams will no longer need to manually rework their entire website infrastructure each time a new feature gets added.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="the-birth-of-docusaurus"></a><a href="#the-birth-of-docusaurus" 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>The Birth of docusaurus</h2>
|
||||
<p><img src="/img/slash-birth.png" alt=""></p>
|
||||
<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 Jekyll template 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 Jekyll 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>
|
||||
|
|
@ -25,7 +25,7 @@
|
|||
<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=""></p>
|
||||
<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
|
||||
|
|
@ -98,7 +98,7 @@
|
|||
│ └── users.html # custom<span class="hljs-built_in"> 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=""></p>
|
||||
<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>
|
||||
<h2><a class="anchor" aria-hidden="true" id="acknowledgements"></a><a href="#acknowledgements" 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>Acknowledgements</h2>
|
||||
<p>Docusaurus wouldn't exist without the work of the rest of the core Docusaurus team: <a href="http://twitter.com/ericnakagawa">Eric Nakagawa</a>, <a href="https://twitter.com/hectorramos">Hector Ramos</a>, <a href="https://twitter.com/EricVicenti">Eric Vicenti</a> and <a href="https://github.com/deltice">Frank Li</a> — a former intern at Facebook who implemented the core technology and features.</p>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue