mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-16 02:27:21 +02:00
147 lines
No EOL
22 KiB
HTML
147 lines
No EOL
22 KiB
HTML
<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta http-equiv="X-UA-Compatible" content="IE=edge"/><title>How I Converted Profilo to Docusaurus in Under 2 Hours · Docusaurus</title><meta name="viewport" content="width=device-width"/><meta name="generator" content="Docusaurus"/><meta name="description" content="> *“Joel and I were discussing having a website and how it would have been great to launch with it. So I challenged myself to add Docusaurus support. It took just over an hour and a half. I'm going to send you a PR with the addition so you can take a look and see if you like it. Your workflow for adding docs wouldn't be much different from editing those markdown files.”*"/><meta property="og:title" content="How I Converted Profilo to Docusaurus in Under 2 Hours · Docusaurus"/><meta property="og:type" content="website"/><meta property="og:url" content="https://docusaurus.io/blog/2018/04/30/How-I-Converted-Profilo-To-Docusaurus"/><meta property="og:description" content="> *“Joel and I were discussing having a website and how it would have been great to launch with it. So I challenged myself to add Docusaurus support. It took just over an hour and a half. I'm going to send you a PR with the addition so you can take a look and see if you like it. Your workflow for adding docs wouldn't be much different from editing those markdown files.”*"/><meta property="og:image" content="https://docusaurus.io/img/docusaurus.png"/><meta name="twitter:card" content="summary"/><meta name="twitter: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/atom-one-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>
|
||
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
||
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
||
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
||
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
|
||
|
||
ga('create', 'UA-44373548-31', 'auto');
|
||
ga('send', 'pageview');
|
||
</script><link rel="stylesheet" href="/css/code-blocks-buttons.css"/><script type="text/javascript" src="https://buttons.github.io/buttons.js"></script><script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js"></script><script type="text/javascript" src="/js/code-blocks-buttons.js"></script><script src="https://unpkg.com/vanilla-back-to-top@7.1.14/dist/vanilla-back-to-top.min.js"></script><script>
|
||
document.addEventListener("DOMContentLoaded", function(){
|
||
addBackToTop(
|
||
{"zIndex":100}
|
||
)
|
||
});
|
||
</script><link rel="stylesheet" href="/css/prism.css"/><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="headerTitleWithLogo">Docusaurus</h2></a><a href="/en/versions"><h3>1.2.0</h3></a><div class="navigationWrapper navigationSlider"><nav class="slidingNav"><ul class="nav-site nav-site-internal"><li class=""><a href="/docs/en/installation" target="_self">Docs</a></li><li class=""><a href="/en/help" target="_self">Help</a></li><li class=""><a href="/en/users" target="_self">Users</a></li><li class=""><a href="/en/about-slash" 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><span><li><a id="languages-menu" href="#"><img class="languages-icon" src="/img/language.svg"/>English</a><div id="languages-dropdown" class="hide"><ul id="languages-dropdown-items"><li><a href="/es-ES">Español</a></li><li><a href="/ro">Română</a></li><li><a href="/tr">Türkçe</a></li><li><a href="/zh-CN">简体中文</a></li><li><a href="https://crowdin.com/project/docusaurus" target="_blank" rel="noreferrer noopener">Help Translate</a></li></ul></div></li><script>
|
||
const languagesMenuItem = document.getElementById("languages-menu");
|
||
const languagesDropDown = document.getElementById("languages-dropdown");
|
||
languagesMenuItem.addEventListener("click", function(){
|
||
if(languagesDropDown.className == "hide") {
|
||
languagesDropDown.className = "visible";
|
||
} else {
|
||
languagesDropDown.className = "hide";
|
||
}
|
||
});
|
||
</script></span><li class="navSearchWrapper reactNavSearchWrapper"><input type="text" id="search_input_react" placeholder="Search" title="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 class="tocToggler" id="tocToggler"><i class="icon-toc"></i></div></div><div class="navGroups"><div class="navGroup navGroupActive"><h3>Recent Posts</h3><ul><li class="navListItem navListItemActive"><a class="navItem navItemActive" href="/blog/2018/04/30/How-I-Converted-Profilo-To-Docusaurus">How I Converted Profilo to Docusaurus in Under 2 Hours</a></li><li class="navListItem"><a class="navItem" href="/blog/2017/12/14/introducing-docusaurus">Introducing Docusaurus</a></li></ul></div></div></section></div><script>
|
||
document.addEventListener('DOMContentLoaded', function() {
|
||
createToggler('#navToggler', '#docsNav', 'docsSliderActive');
|
||
createToggler('#tocToggler', 'body', 'tocActive');
|
||
|
||
const headings = document.querySelector('.toc-headings');
|
||
headings && headings.addEventListener('click', function(event) {
|
||
if (event.target.tagName === 'A') {
|
||
document.body.classList.remove('tocActive');
|
||
}
|
||
}, false);
|
||
|
||
function createToggler(togglerSelector, targetSelector, className) {
|
||
var toggler = document.querySelector(togglerSelector);
|
||
var target = document.querySelector(targetSelector);
|
||
|
||
toggler.onclick = function(event) {
|
||
event.preventDefault();
|
||
|
||
target.classList.toggle(className);
|
||
};
|
||
}
|
||
});
|
||
</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/2018/04/30/How-I-Converted-Profilo-To-Docusaurus">How I Converted Profilo to Docusaurus in Under 2 Hours</a></h1><p class="post-meta">April 30, 2018</p><div class="authorBlock"><p class="post-authorName"><a href="http://twitter.com/abernathyca" target="_blank" rel="noreferrer noopener">Christine Abernathy</a></p><div class="authorPhoto"><a href="http://twitter.com/abernathyca" target="_blank" rel="noreferrer noopener"><img src="https://graph.facebook.com/1424840234/picture/?height=200&width=200" alt="Christine Abernathy"/></a></div></div></header><div><span><blockquote>
|
||
<p><em>“Joel and I were discussing having a website and how it would have been great to launch with it. So I challenged myself to add Docusaurus support. It took just over an hour and a half. I'm going to send you a PR with the addition so you can take a look and see if you like it. Your workflow for adding docs wouldn't be much different from editing those markdown files.”</em></p>
|
||
<p><em>— Note sent to the Profilo team</em></p>
|
||
</blockquote>
|
||
<p>This is the story of the rather short journey it took to create the <a href="https://facebookincubator.github.io/profilo/">Profilo</a> website using Docusaurus.</p>
|
||
<p>Profilo, an Android library for collecting performance traces from production, <a href="https://code.facebook.com/posts/356115241551826/profilo-understanding-app-performance-in-the-wild/">was announced</a> earlier this year. The project was <a href="https://github.com/facebookincubator/profilo/tree/802042f90f990998a272387e371b893af52465b8">published on GitHub</a> with a less than <a href="https://github.com/facebookincubator/profilo/tree/802042f90f990998a272387e371b893af52465b8/docs">a handful or Markdown files</a> to describe its functionality and no website to showcase any branding and highlight the logo. The task at hand was to turn these existing docs and logo into a website.</p>
|
||
<!--truncate-->
|
||
<p>In general, when creating a website with Docusaurus you do the following:</p>
|
||
<ol>
|
||
<li>Generate a template website using Docusaurus scripts.</li>
|
||
<li>Customize the generated template files for your desired site colors and your project configuration (ex: website and GitHub links).</li>
|
||
<li>Create the website content:
|
||
<ol>
|
||
<li>Add your docs and any supporting assets.</li>
|
||
<li>Customize the default landing page provided by Docusaurus to suit your needs.</li>
|
||
<li>Configure the default site navigation file.</li>
|
||
</ol></li>
|
||
<li>Publish the website and set up how it will be published for future changes.</li>
|
||
</ol>
|
||
<p>Given I had pre-existing Markdown files, I didn't have to generate the core content but simply make sure that Docusaurus could process the files by adding the expected metadata to them. Most of the work would therefore consist of customizing the defaults provided by Docusaurus.</p>
|
||
<h2><a class="anchor" aria-hidden="true" id="overview-of-steps-taken"></a><a href="#overview-of-steps-taken" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" 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>Overview of Steps Taken</h2>
|
||
<p>Here's an overview of the steps taken to convert to a website. I'll discuss some of the design aspects in a later section.</p>
|
||
<p><strong>Design and colors:</strong></p>
|
||
<ol>
|
||
<li>Got all the desired logo formats from designer. I had to create the <em>.favicon</em> one.</li>
|
||
<li>Worked out some passable primary and secondary website colors using the <a href="http://paletton.com/">http://paletton.com/</a> tools - very handy!</li>
|
||
</ol>
|
||
<p><strong>Initial website setup:</strong></p>
|
||
<ol>
|
||
<li>Forked the <a href="https://github.com/facebookincubator/profilo/">Profilo project</a> on GitHub and created a local clone of the fork to set up the website.</li>
|
||
<li>Created the initial Docusaurus website using the <a href="https://docusaurus.io/docs/en/installation.html">installation instructions</a>.</li>
|
||
<li>Deleted the <code>docs-examples-from-docusaurus</code> and <code>website/blog-examples-from-docusaurus</code> folders as these would not be needed. Profilo had existing docs we could use and there was no need for blogs at this time.</li>
|
||
</ol>
|
||
<p><strong>Content creation:</strong></p>
|
||
<ol>
|
||
<li><p>Added metadata to the existing Markdown files found in the <code>docs</code> folder, for example:</p>
|
||
<pre><code class="hljs"> +---
|
||
+id: architecture
|
||
+title: Architecture
|
||
+sidebar_label: Architecture
|
||
+---
|
||
</code></pre></li>
|
||
<li><p>Added the logo assets to the <code>website/static/img</code> folder.</p></li>
|
||
<li><p>Modified <code>website/pages/en/index.js</code>, the landing page, to highlight Profilo features.</p></li>
|
||
<li><p>Modified <code>website/core/Footer.js</code>, the footer, to simplify it for Profilo.</p></li>
|
||
<li><p>Edited <code>website/siteConfig.js</code> (website configuration file) to specify the previously chosen primary and secondary colors.</p></li>
|
||
<li><p>Modified <code>website/sidebars.json</code> that specifies the sidebar navigation. Listed all the docs and customized it based on the metadata added to the Markdown files.</p></li>
|
||
<li><p>Edited the website configuration file to specify the GitHub properties, logo images, header links, and the website link.</p></li>
|
||
<li><p>Tested the website locally throughout this phase. (I ran <code>yarn start</code> from the <code>website</code> folder to start the server.)</p></li>
|
||
</ol>
|
||
<p><strong>Feedback and review changes:</strong></p>
|
||
<ol>
|
||
<li>Sent a <a href="https://github.com/facebookincubator/profilo/pull/6">pull request</a> to the project.</li>
|
||
<li>Updated the colors after the designer rightly gasped at the ones I had chosen (IANAD).</li>
|
||
<li>Updated the colors and updated the PR.</li>
|
||
<li>The PR was then accepted and <a href="https://github.com/facebookincubator/profilo/commit/6ad033aaf5a7d54e6d842f45a5bccd051a8e45ad">merged</a>. Yay!</li>
|
||
</ol>
|
||
<p><strong>Website publishing:</strong></p>
|
||
<ol>
|
||
<li><p>Pushed the first website version by running the Docusaurus publish script from the command line:</p>
|
||
<pre><code class="hljs"> USE_SSH=true \
|
||
GIT_USER=caabernathy \
|
||
CURRENT_BRANCH=master \
|
||
yarn run publish-gh-pages
|
||
</code></pre></li>
|
||
<li><p>Configured Circle CI using the <a href="https://docusaurus.io/docs/en/publishing.html#automating-deployments-using-continuous-integration">provided Docusaurus instructions</a>. There were 2 PRs for this, <a href="https://github.com/facebookincubator/profilo/pull/8">the first</a>for the initial config and <a href="https://github.com/facebookincubator/profilo/pull/12">the second</a> to make sure Circle CI only triggered for changes in the master branch (thanks Joel Marcey!).</p></li>
|
||
</ol>
|
||
<p>The final website was published on <a href="https://facebookincubator.github.io/profilo/">https://facebookincubator.github.io/profilo/</a>. 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.</p>
|
||
<h2><a class="anchor" aria-hidden="true" id="design"></a><a href="#design" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" 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>Design</h2>
|
||
<p>Here's what the initial website looked like when the first pull request was sent out:</p>
|
||
<p><img src="/img/profilo_blog_post_website_initial.png" alt="Website Initial Design"></p>
|
||
<p>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.</p>
|
||
<p><img src="/img/profilo_blog_post_photoshop_color_picker.png" alt="Picking Color Photoshop"></p>
|
||
<p>I then took the RGB representation of the color and set it as the baseline color on <a href="http://paletton.com/">Paletton</a>. The website then gave me various color options to try on the website by editing the Docusaurus website configuration file.</p>
|
||
<p><img src="/img/profilo_blog_post_palette_website_color_picker.png" alt="Picking Color Paletton"></p>
|
||
<p>The selected primary and secondary colors were a good jumping off point for designer feedback.</p>
|
||
<p>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.</p>
|
||
<p>Here's what the final website looked like:</p>
|
||
<p><img src="/img/profilo_blog_post_website_final.png" alt="Website Final Design"></p>
|
||
<p>This is an example page showing the core content, in this case the Getting Started page:</p>
|
||
<p><img src="/img/profilo_blog_post_website_final_docs.png" alt="Website Docs Example"></p>
|
||
<p>This also shows the sidebar structure that was set up through editing <code>website/sidebars.json</code>.</p>
|
||
<p>Lastly, I didn't have to worry about handling responsive design. You get this out of the box with Docusaurus!</p>
|
||
<p><img src="/img/profilo_blog_post_android_ios.png" alt="Mobile Site"></p>
|
||
<h2><a class="anchor" aria-hidden="true" id="final-thoughts"></a><a href="#final-thoughts" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" 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>Final Thoughts</h2>
|
||
<p>The Profilo engineers were happy to see that they didn't have to change their workflow to update existing content. They were able to continue working with Markdown files. This will still be true in the future if new docs are added, although there may be some config changes needed if the sidebar navigation needs to be updated.</p>
|
||
<p>The infrastructure provided by Docusaurus made it easy to convert Markdown files into a working website. Even though the project had only three docs, this gave Profilo a more professional look. So, it was well worth the short time investment to get it done.</p>
|
||
</span></div></div><div class="blogSocialSection"><div class="blogSocialSectionItem"><a href="https://twitter.com/share" class="twitter-share-button" data-text="How I Converted Profilo to Docusaurus in Under 2 Hours" data-url="https://docusaurus.io/blog/2018/04/30/How-I-Converted-Profilo-To-Docusaurus" data-related="true" data-via="abernathyca" data-show-count="false"></a></div><div class="blogSocialSectionItem"><div class="fb-like" data-href="https://docusaurus.io/blog/2018/04/30/How-I-Converted-Profilo-To-Docusaurus" data-layout="standard" data-share="true" data-width="225" data-show-faces="false"></div></div><div class="blogSocialSectionItem"><div class="fb-comments" data-href="https://docusaurus.io/blog/2018/04/30/How-I-Converted-Profilo-To-Docusaurus" data-width="100%" data-numposts="5" data-order-by="time"></div></div></div></div><div class="blog-recent"><a class="button" href="/blog">Recent Posts</a></div></div></div><nav class="onPageNav"><ul class="toc-headings"><li><a href="#overview-of-steps-taken">Overview of Steps Taken</a></li><li><a href="#design">Design</a></li><li><a href="#final-thoughts">Final Thoughts</a></li></ul></nav></div><footer class="nav-footer" id="footer"><section class="sitemap"><a href="/" class="nav-home"><img src="/img/docusaurus_monochrome.svg" alt="Docusaurus" width="66" height="58"/></a><div><h5>Docs</h5><a href="
|
||
/docs/en/installation.html">Getting Started</a><a href="
|
||
/docs/en/versioning.html">Versioning</a><a href="
|
||
/docs/en/translation.html">Localization</a><a href="
|
||
/docs/en/search.html">Adding Search</a></div><div><h5>Community</h5><a href="/en/users.html">User Showcase</a></div><div><h5>More</h5><div class="social"><a class="github-button" href="https://github.com/facebook/Docusaurus" data-count-href="/facebook/Docusaurus/stargazers" data-show-count="true" data-count-aria-label="# stargazers on GitHub" aria-label="Star this project on GitHub">Docusaurus</a></div><div class="social"><a href="https://twitter.com/docusaurus" class="twitter-follow-button">Follow @docusaurus</a></div><div class="social"><div class="fb-like" data-href="https://docusaurus.io" data-layout="standard" data-share="true" data-width="225" data-show-faces="false"></div></div></div></section><a href="https://code.facebook.com/projects/" target="_blank" rel="noreferrer noopener" class="fbOpenSource"><img src="/img/oss_logo.png" alt="Facebook Open Source" width="170" height="45"/></a><section class="copyright"><span>Copyright © 2018 Facebook Inc.</span></section></footer></div><script type="text/javascript" src="https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.js"></script><script>window.fbAsyncInit = function() {FB.init({appId:'199138890728411',xfbml:true,version:'v2.7'});};(function(d, s, id){var js, fjs = d.getElementsByTagName(s)[0];if (d.getElementById(id)) {return;}js = d.createElement(s); js.id = id;js.src = '//connect.facebook.net/en_US/sdk.js';fjs.parentNode.insertBefore(js, fjs);}(document, 'script','facebook-jssdk'));
|
||
</script><script>window.twttr=(function(d,s, id){var js,fjs=d.getElementsByTagName(s)[0],t=window.twttr||{};if(d.getElementById(id))return t;js=d.createElement(s);js.id=id;js.src='https://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js, fjs);t._e = [];t.ready = function(f) {t._e.push(f);};return t;}(document, 'script', 'twitter-wjs'));</script><script>
|
||
var search = docsearch({
|
||
|
||
apiKey: '3eb9507824b8be89e7a199ecaa1a9d2c',
|
||
indexName: 'docusaurus',
|
||
inputSelector: '#search_input_react'
|
||
});
|
||
</script></body></html> |