gitea/documentation.federated.computer
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
8ee490297b
documentation.federated.com.../public/docs/contribution-guidelines/index.html

425 lines
38 KiB
HTML
Raw Normal View History

initial
2023-05-30 17:55:11 +00:00
<!doctype html>
<html itemscope itemtype="http://schema.org/WebPage" lang="en" class="no-js">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<meta name="generator" content="Hugo 0.92.2" />
<link rel="alternate" type="text/html" href="/docs/contribution-guidelines/_print/">
<link rel="alternate" type="application/rss&#43;xml" href="/docs/contribution-guidelines/index.xml">
<meta name="robots" content="index, follow">
<link rel="shortcut icon" href="/favicons/favicon.ico" >
<link rel="apple-touch-icon" href="/favicons/apple-touch-icon-180x180.png" sizes="180x180">
<link rel="icon" type="image/png" href="/favicons/favicon-16x16.png" sizes="16x16">
<link rel="icon" type="image/png" href="/favicons/favicon-32x32.png" sizes="32x32">
<link rel="icon" type="image/png" href="/favicons/android-36x36.png" sizes="36x36">
<link rel="icon" type="image/png" href="/favicons/android-48x48.png" sizes="48x48">
<link rel="icon" type="image/png" href="/favicons/android-72x72.png" sizes="72x72">
<link rel="icon" type="image/png" href="/favicons/android-96x96.png" sizes="96x96">
<link rel="icon" type="image/png" href="/favicons/android-144x144.png" sizes="144x144">
<link rel="icon" type="image/png" href="/favicons/android-192x192.png" sizes="192x192">
<title>Contribution Guidelines | Federated Docs</title>
<meta name="description" content="How to contribute to the docs
">
<meta property="og:title" content="Contribution Guidelines" />
<meta property="og:description" content="How to contribute to the docs
" />
<meta property="og:type" content="website" />
<meta property="og:url" content="/docs/contribution-guidelines/" />
<meta itemprop="name" content="Contribution Guidelines">
<meta itemprop="description" content="How to contribute to the docs
"><meta name="twitter:card" content="summary"/>
<meta name="twitter:title" content="Contribution Guidelines"/>
<meta name="twitter:description" content="How to contribute to the docs
"/>
<link rel="preload" href="/scss/main.min.43ad6541a45f31cd03dd1066a29ba2595ef582b492c6241a2288367893840e77.css" as="style">
<link href="/scss/main.min.43ad6541a45f31cd03dd1066a29ba2595ef582b492c6241a2288367893840e77.css" rel="stylesheet" integrity="">
<script
src="https://code.jquery.com/jquery-3.6.0.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK"
crossorigin="anonymous"></script>
</head>
<body class="td-section">
<header>
<nav class="js-navbar-scroll navbar navbar-expand navbar-dark flex-column flex-md-row td-navbar">
<a class="navbar-brand" href="/"><span class="navbar-brand__logo navbar-logo"><svg id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 500 500" style="enable-background:new 0 0 500 500"><g><path style="fill:#fff" d="M116.8525 421.9722c-5.7041.0-10.3442-4.3127-10.3442-9.6129V88.183c0-5.3002 4.6401-9.6117 10.3442-9.6117H320.858c3.0347.0 9.3959.5498 11.7506 2.6302l.3545.3442 58.905 63.2912c2.3101 2.491 2.9202 8.4928 2.9202 11.3184v256.2039c0 5.3002-4.6407 9.6129-10.3436 9.6129H116.8525z"/><g><g><g><path style="fill:#767676" d="M384.4445 423.2066H116.852c-6.3839.0-11.5786-4.8658-11.5786-10.8474V88.1831c0-5.9804 5.1947-10.8461 11.5786-10.8461h204.0062c.377.0 9.2786.0329 12.568 2.9389l.3947.3833 58.9508 63.337c3.2135 3.4652 3.2514 11.7924 3.2514 12.1593v256.2036C396.0231 418.3408 390.8284 423.2066 384.4445 423.2066zM116.5079 411.9189c.0848.0278.1999.0531.3441.0531h267.5925c.1442.0.2581-.0253.3441-.0531V156.1556c-.0076-.9033-.3593-3.7347-.7034-5.0037l-57.6527-61.9416c-1.4651-.3176-4.4533-.6389-5.5742-.6389H116.852c-.143.0-.2594.024-.3441.0531V411.9189zm267.4533-261.149zM327.0321 89.371v.0013V89.371z"/></g></g></g><g><g><path style="fill:#5b7fc0" d="M189.0874 210.1754l.0012-.0012c7.7751.0012 15.0295 4.1862 18.932 10.9234 1.9177 3.3159 2.9305 7.1011 2.9293 10.9378.0 5.8394-2.2733 11.3304-6.4032 15.4604-4.1288 4.1288-9.6186 6.4032-15.458 6.4032s-11.328-2.2733-15.458-6.4032-6.4032-9.6186-6.4056-15.4628c.0012-6.025 2.454-11.4897 6.4116-15.4473C177.5953 212.627 183.0601 210.1742 189.0874 210.1754zm7.993 21.8576c.0012-1.4042-.3687-2.7868-1.063-3.9887-1.4293-2.4684-4.0833-3.9995-6.9299-4.0019-4.4077.0024-7.993 3.5877-7.993 7.993.0 2.1356.832 4.1431 2.3427 5.6539 1.5083 1.5083 3.5159 2.3403 5.6503 2.3415 2.1356.0 4.1443-.8308 5.6539-2.3403S197.0816 234.1722 197.0804 232.033z"/><path style="opacity:.3;fill:#fff" d="M189.0898 210.176c7.7763.0 15.0283 4.1826 18.926 10.9151 1.9201 3.3136 2.9377 7.0988 2.9353 10.9462.0024 12.0643-9.8065 21.8636-21.8613 21.8613-12.0547.0024-21.8636-9.8066-21.8612-21.8613.0-6.0285 2.4516-11.4921 6.4116-15.452C177.5977 212.6276 183.0612 210.176 189.0898 210.176zm7.9941 21.8612c0-1.4078-.3711-2.7892-1.0702-3.9959-1.4269-2.466-4.0797-3.9983-6.924-3.9983-4.4005-.0048-7.9918 3.5817-7.9942 7.9942.0024 4.4077 3.5865 7.9918 7.9942 7.9942 2.2027.0 4.2018-.8978 5.6479-2.3439C196.1861 236.239 197.0839 234.2399 197.0839 232.0372z"/><g><defs><path id="SVGID_1_" d="M194.7376 237.6875c-1.4461 1.4461-3.4452 2.3439-5.6479 2.3439-4.4077-.0024-7.9918-3.5865-7.9942-7.9942.0024-4.4125 3.5937-7.999 7.9942-7.9942 2.8443.0 5.497 1.5323 6.924 3.9983.6991 1.2067 1.0702 2.5881 1.0702 3.9959C197.0839 234.2399 196.1861 236.239 194.7376 237.6875z"/></defs><clipPath id="SVGID_2_"><use xlink:href="#SVGID_1_" style="overflow:visible"/></clipPath><path style="clip-path:url(#SVGID_2_);fill:#fff" d="M190.0704 225.0237c-4.4005-.0048-7.9918 3.5817-7.9942 7.9942.0011 1.9546.7088 3.7452 1.8782 5.1354-1.7447-1.4674-2.8575-3.663-2.8588-6.116.0024-4.4125 3.5936-7.999 7.9942-7.9942 2.3802-1e-4 4.616 1.0833 6.1218 2.8788C193.7885 225.7247 191.9774 225.0237 190.0704 225.0237z"/><path style="opacity:.13;clip-path:url(#SVGID_2_);fill:#020202" d="M190.0704 225.0237c-4.4005-.0048-7.9918 3.5817-7.9942 7.9942.0011 1.9546.7088 3.7452 1.8782 5.1354-1.7447-1.4674-2.8575-3.663-2.8588-6.116.0024-4.4125 3.5936-7.999 7.9942-7.9942 2.3802-1e-4 4.616 1.0833 6.1218 2.8788C193.7885 225.7247 191.9774 225.0237 190.0704 225.0237z"/></g><g><defs><path id="SVGID_3_" d="M189.0898 210.176c7.7763.0 15.0283 4.1826 18.926 10.9151 1.9201 3.3136 2.9377 7.0988 2.9353 10.9462.0024 12.0643-9.8065 21.8636-21.8613 21.8613-12.0547.0024-21.8636-9.8066-21.8612-21.8613.0-6.0285 2.4516-11.4921 6.4116-15.452C177.5977 212.6276 183.0612 210.176 189.0898 210.176zm7.9941 21.8612c0-1.4078-.3711-2.7892-1.0702-3.9959-1.4269-2.466-4.0797-3.9983-6.924-3.9983-4.4005-.0048-7.9918 3.5817-7.9942 7.9942.0024 4.4077 3.5865 7.9918 7.9942 7.9942 2.2027.0 4.2018-.8978 5.6479-2.3439C196.1861 236.239 197.0839 234.2399 197.0839 232.0372z"/></defs><clipPath id="
<div class="td-navbar-nav-scroll ml-md-auto" id="main_navbar">
<ul class="navbar-nav mt-2 mt-lg-0">
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="/about/"><span>About</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link active" href="/docs/"><span class="active">Documentation</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="/blog/"><span>Blog</span></a>
</li>
<li class="nav-item mr-4 mb-2 mb-lg-0">
<a class="nav-link" href="/community/"><span>Community</span></a>
</li>
</ul>
</div>
<div class="navbar-nav d-none d-lg-block">
</div>
</nav>
</header>
<div class="container-fluid td-outer">
<div class="td-main">
<div class="row flex-xl-nowrap">
<aside class="col-12 col-md-3 col-xl-2 td-sidebar d-print-none">
<div id="td-sidebar-menu" class="td-sidebar__inner">
<form class="td-sidebar__search d-flex align-items-center">
<button class="btn btn-link td-sidebar__toggle d-md-none p-0 ml-3 fas fa-bars" type="button" data-toggle="collapse" data-target="#td-section-nav" aria-controls="td-section-nav" aria-expanded="false" aria-label="Toggle section navigation">
</button>
</form>
<nav class="collapse td-sidebar-nav" id="td-section-nav">
<ul class="td-sidebar-nav__section pr-md-3 ul-0">
<li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child active-path" id="m-docs-li">
<a href="/docs/" class="align-left pl-0 td-sidebar-link td-sidebar-link__section tree-root" id="m-docs"><span class="">Documentation</span></a>
<ul class="ul-1">
<li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id="m-docsoverview-li">
<a href="/docs/overview/" class="align-left pl-0 td-sidebar-link td-sidebar-link__section" id="m-docsoverview"><span class="">Overview</span></a>
</li><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id="m-docsgetting-started-li">
<a href="/docs/getting-started/" class="align-left pl-0 td-sidebar-link td-sidebar-link__section" id="m-docsgetting-started"><span class="">Getting Started</span></a>
<ul class="ul-2 foldable">
<li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id="m-docsgetting-startedexample-page-li">
<a href="/docs/getting-started/example-page/" class="align-left pl-0 td-sidebar-link td-sidebar-link__page" id="m-docsgetting-startedexample-page"><span class="">Example Page</span></a>
</li>
</ul>
</li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id="m-docsexamples-li">
<a href="/docs/examples/" class="align-left pl-0 td-sidebar-link td-sidebar-link__section" id="m-docsexamples"><span class="">Examples</span></a>
</li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id="m-docsconcepts-li">
<a href="/docs/concepts/" class="align-left pl-0 td-sidebar-link td-sidebar-link__section" id="m-docsconcepts"><span class="">Concepts</span></a>
</li><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id="m-docstasks-li">
<a href="/docs/tasks/" class="align-left pl-0 td-sidebar-link td-sidebar-link__section" id="m-docstasks"><span class="">Core Tasks</span></a>
<ul class="ul-2 foldable">
<li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id="m-docstasksbeds-li">
<a href="/docs/tasks/beds/" class="align-left pl-0 td-sidebar-link td-sidebar-link__page" id="m-docstasksbeds"><span class="">Bed and Chair Metrics</span></a>
</li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id="m-docstasksporridge-li">
<a href="/docs/tasks/porridge/" class="align-left pl-0 td-sidebar-link td-sidebar-link__page" id="m-docstasksporridge"><span class="">Porridge Assessment</span></a>
</li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id="m-docstaskstask-li">
<a href="/docs/tasks/task/" class="align-left pl-0 td-sidebar-link td-sidebar-link__page" id="m-docstaskstask"><span class="">Another Task</span></a>
</li><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id="m-docstasksponycopters-li">
<a href="/docs/tasks/ponycopters/" class="align-left pl-0 td-sidebar-link td-sidebar-link__section" id="m-docstasksponycopters"><span class="">Working with Ponycopters</span></a>
<ul class="ul-3 foldable">
<li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id="m-docstasksponycoptersconfiguring-ponycopters-li">
<a href="/docs/tasks/ponycopters/configuring-ponycopters/" class="align-left pl-0 td-sidebar-link td-sidebar-link__page" id="m-docstasksponycoptersconfiguring-ponycopters"><span class="">Configuring Ponycopters</span></a>
</li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id="m-docstasksponycopterslaunching-ponycopters-li">
<a href="/docs/tasks/ponycopters/launching-ponycopters/" class="align-left pl-0 td-sidebar-link td-sidebar-link__page" id="m-docstasksponycopterslaunching-ponycopters"><span class="">Launching Ponycopters</span></a>
</li>
</ul>
</li>
</ul>
</li><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id="m-docstutorials-li">
<a href="/docs/tutorials/" class="align-left pl-0 td-sidebar-link td-sidebar-link__section" id="m-docstutorials"><span class="">Tutorials</span></a>
<ul class="ul-2 foldable">
<li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id="m-docstutorialsmulti-bear-li">
<a href="/docs/tutorials/multi-bear/" class="align-left pl-0 td-sidebar-link td-sidebar-link__page" id="m-docstutorialsmulti-bear"><span class="">Multi-Bear Domicile Setup</span></a>
</li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id="m-docstutorialstutorial2-li">
<a href="/docs/tutorials/tutorial2/" class="align-left pl-0 td-sidebar-link td-sidebar-link__page" id="m-docstutorialstutorial2"><span class="">Another Tutorial</span></a>
</li>
</ul>
</li><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id="m-docsreference-li">
<a href="/docs/reference/" class="align-left pl-0 td-sidebar-link td-sidebar-link__section" id="m-docsreference"><span class="">Reference</span></a>
<ul class="ul-2 foldable">
<li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id="m-docsreferenceparameter-reference-li">
<a href="/docs/reference/parameter-reference/" class="align-left pl-0 td-sidebar-link td-sidebar-link__page" id="m-docsreferenceparameter-reference"><span class="">Parameter Reference</span></a>
</li>
</ul>
</li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child active-path" id="m-docscontribution-guidelines-li">
<a href="/docs/contribution-guidelines/" class="align-left pl-0 active td-sidebar-link td-sidebar-link__section" id="m-docscontribution-guidelines"><span class="td-sidebar-nav-active-item">Contribution Guidelines</span></a>
</li>
</ul>
</li>
</ul>
</nav>
</div>
</aside>
<aside class="d-none d-xl-block col-xl-2 td-sidebar-toc d-print-none">
<div class="td-page-meta ml-2 pb-1 pt-2 mb-0">
<a href="https://github.com/google/docsy-example/tree/main/content/en/docs/Contribution%20guidelines/_index.md" class="td-page-meta--view" target="_blank" rel="noopener"><i class="fa-solid fa-file-lines fa-fw"></i> View page source</a>
<a href="https://github.com/google/docsy-example/edit/main/content/en/docs/Contribution%20guidelines/_index.md" class="td-page-meta--edit" target="_blank" rel="noopener"><i class="fa-solid fa-pen-to-square fa-fw"></i> Edit this page</a>
<a href="https://github.com/google/docsy-example/new/main/content/en/docs/Contribution%20guidelines/_index.md?filename=change-me.md&amp;value=---%0Atitle%3A&#43;%22Long&#43;Page&#43;Title%22%0AlinkTitle%3A&#43;%22Short&#43;Nav&#43;Title%22%0Aweight%3A&#43;100%0Adescription%3A&#43;%3E-%0A&#43;&#43;&#43;&#43;&#43;Page&#43;description&#43;for&#43;heading&#43;and&#43;indexes.%0A---%0A%0A%23%23&#43;Heading%0A%0AEdit&#43;this&#43;template&#43;to&#43;create&#43;your&#43;new&#43;page.%0A%0A%2A&#43;Give&#43;it&#43;a&#43;good&#43;name%2C&#43;ending&#43;in&#43;%60.md%60&#43;-&#43;e.g.&#43;%60getting-started.md%60%0A%2A&#43;Edit&#43;the&#43;%22front&#43;matter%22&#43;section&#43;at&#43;the&#43;top&#43;of&#43;the&#43;page&#43;%28weight&#43;controls&#43;how&#43;its&#43;ordered&#43;amongst&#43;other&#43;pages&#43;in&#43;the&#43;same&#43;directory%3B&#43;lowest&#43;number&#43;first%29.%0A%2A&#43;Add&#43;a&#43;good&#43;commit&#43;message&#43;at&#43;the&#43;bottom&#43;of&#43;the&#43;page&#43;%28%3C80&#43;characters%3B&#43;use&#43;the&#43;extended&#43;description&#43;field&#43;for&#43;more&#43;detail%29.%0A%2A&#43;Create&#43;a&#43;new&#43;branch&#43;so&#43;you&#43;can&#43;preview&#43;your&#43;new&#43;file&#43;and&#43;request&#43;a&#43;review&#43;via&#43;Pull&#43;Request.%0A" class="td-page-meta--child" target="_blank" rel="noopener"><i class="fa-solid fa-pen-to-square fa-fw"></i> Create child page</a>
<a href="https://github.com/google/docsy-example/issues/new?title=Contribution%20Guidelines" class="td-page-meta--issue" target="_blank" rel="noopener"><i class="fa-solid fa-list-check fa-fw"></i> Create documentation issue</a>
<a id="print" href="/docs/contribution-guidelines/_print/"><i class="fa-solid fa-print fa-fw"></i> Print entire section</a>
</div>
<div class="td-toc">
<nav id="TableOfContents">
<ul>
<li><a href="#quick-start-with-netlify">Quick start with Netlify</a></li>
<li><a href="#updating-a-single-page">Updating a single page</a></li>
<li><a href="#previewing-your-changes-locally">Previewing your changes locally</a></li>
<li><a href="#creating-an-issue">Creating an issue</a></li>
<li><a href="#useful-resources">Useful resources</a></li>
</ul>
</nav>
</div>
<div class="taxonomy taxonomy-terms-cloud taxo-tags">
<h5 class="taxonomy-title">Tag Cloud</h5>
<ul class="taxonomy-terms">
<li><a class="taxonomy-term" href="/tags/docs/" data-taxonomy-term="docs"><span class="taxonomy-label">docs</span><span class="taxonomy-count">2</span></a></li>
<li><a class="taxonomy-term" href="/tags/sample/" data-taxonomy-term="sample"><span class="taxonomy-label">sample</span><span class="taxonomy-count">1</span></a></li>
<li><a class="taxonomy-term" href="/tags/test/" data-taxonomy-term="test"><span class="taxonomy-label">test</span><span class="taxonomy-count">2</span></a></li>
</ul>
</div>
<div class="taxonomy taxonomy-terms-cloud taxo-categories">
<h5 class="taxonomy-title">Categories</h5>
<ul class="taxonomy-terms">
<li><a class="taxonomy-term" href="/categories/examples/" data-taxonomy-term="examples"><span class="taxonomy-label">Examples</span><span class="taxonomy-count">2</span></a></li>
<li><a class="taxonomy-term" href="/categories/placeholders/" data-taxonomy-term="placeholders"><span class="taxonomy-label">Placeholders</span><span class="taxonomy-count">1</span></a></li>
</ul>
</div>
</aside>
<main class="col-12 col-md-9 col-xl-8 pl-md-5" role="main">
<nav aria-label="breadcrumb" class="td-breadcrumbs">
<ol class="breadcrumb">
<li class="breadcrumb-item">
<a href="/docs/">Documentation</a>
</li>
<li class="breadcrumb-item active" aria-current="page">
<a href="/docs/contribution-guidelines/" aria-disabled="true" class="btn-link disabled">Contribution Guidelines</a>
</li>
</ol>
</nav>
<div class="td-content">
<h1>Contribution Guidelines</h1>
<div class="lead">How to contribute to the docs</div>
<header class="article-meta">
</header>
<div class="pageinfo pageinfo-primary">
<p>These basic sample guidelines assume that your Docsy site is deployed using Netlify and your files are stored in GitHub. You can use the guidelines &ldquo;as is&rdquo; or adapt them with your own instructions: for example, other deployment options, information about your doc project&rsquo;s file structure, project-specific review guidelines, versioning guidelines, or any other information your users might find useful when updating your site. <a href="https://github.com/kubeflow/website/blob/master/README.md">Kubeflow</a> has a great example.</p>
<p>Don&rsquo;t forget to link to your own doc repo rather than our example site! Also make sure users can find these guidelines from your doc repo README: either add them there and link to them from this page, add them here and link to them from the README, or include them in both locations.</p>
</div>
<p>We use <a href="https://gohugo.io/">Hugo</a> to format and generate our website, the
<a href="https://github.com/google/docsy">Docsy</a> theme for styling and site structure,
and <a href="https://www.netlify.com/">Netlify</a> to manage the deployment of the site.
Hugo is an open-source static site generator that provides us with templates,
content organisation in a standard directory structure, and a website generation
engine. You write the pages in Markdown (or HTML if you want), and Hugo wraps them up into a website.</p>
<p>All submissions, including submissions by project members, require review. We
use GitHub pull requests for this purpose. Consult
<a href="https://help.github.com/articles/about-pull-requests/">GitHub Help</a> for more
information on using pull requests.</p>
<h2 id="quick-start-with-netlify">Quick start with Netlify</h2>
<p>Here&rsquo;s a quick guide to updating the docs. It assumes you&rsquo;re familiar with the
GitHub workflow and you&rsquo;re happy to use the automated preview of your doc
updates:</p>
<ol>
<li>Fork the <a href="https://github.com/google/docsy-example">Goldydocs repo</a> on GitHub.</li>
<li>Make your changes and send a pull request (PR).</li>
<li>If you&rsquo;re not yet ready for a review, add &ldquo;WIP&rdquo; to the PR name to indicate
it&rsquo;s a work in progress. (<strong>Don&rsquo;t</strong> add the Hugo property
&ldquo;draft = true&rdquo; to the page front matter, because that prevents the
auto-deployment of the content preview described in the next point.)</li>
<li>Wait for the automated PR workflow to do some checks. When it&rsquo;s ready,
you should see a comment like this: <strong>deploy/netlify — Deploy preview ready!</strong></li>
<li>Click <strong>Details</strong> to the right of &ldquo;Deploy preview ready&rdquo; to see a preview
of your updates.</li>
<li>Continue updating your doc and pushing your changes until you&rsquo;re happy with
the content.</li>
<li>When you&rsquo;re ready for a review, add a comment to the PR, and remove any
&ldquo;WIP&rdquo; markers.</li>
</ol>
<h2 id="updating-a-single-page">Updating a single page</h2>
<p>If you&rsquo;ve just spotted something you&rsquo;d like to change while using the docs, Docsy has a shortcut for you:</p>
<ol>
<li>Click <strong>Edit this page</strong> in the top right hand corner of the page.</li>
<li>If you don&rsquo;t already have an up to date fork of the project repo, you are prompted to get one - click <strong>Fork this repository and propose changes</strong> or <strong>Update your Fork</strong> to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode.</li>
<li>Follow the rest of the <a href="#quick-start-with-netlify">Quick start with Netlify</a> process above to make, preview, and propose your changes.</li>
</ol>
<h2 id="previewing-your-changes-locally">Previewing your changes locally</h2>
<p>If you want to run your own local Hugo server to preview your changes as you work:</p>
<ol>
<li>
<p>Follow the instructions in <a href="/docs/getting-started">Getting started</a> to install Hugo and any other tools you need. You&rsquo;ll need at least <strong>Hugo version 0.45</strong> (we recommend using the most recent available version), and it must be the <strong>extended</strong> version, which supports SCSS.</p>
</li>
<li>
<p>Fork the <a href="https://github.com/google/docsy-example">Goldydocs repo</a> repo into your own project, then create a local copy using <code>git clone</code>. Don’t forget to use <code>--recurse-submodules</code> or you won’t pull down some of the code you need to generate a working site.</p>
<pre tabindex="0"><code>git clone --recurse-submodules --depth 1 https://github.com/google/docsy-example.git
</code></pre></li>
<li>
<p>Run <code>hugo server</code> in the site root directory. By default your site will be available at http://localhost:1313/. Now that you&rsquo;re serving your site locally, Hugo will watch for changes to the content and automatically refresh your site.</p>
</li>
<li>
<p>Continue with the usual GitHub workflow to edit files, commit them, push the
changes up to your fork, and create a pull request.</p>
</li>
</ol>
<h2 id="creating-an-issue">Creating an issue</h2>
<p>If you&rsquo;ve found a problem in the docs, but you&rsquo;re not sure how to fix it yourself, please create an issue in the <a href="https://github.com/google/docsy-example/issues">Goldydocs repo</a>. You can also create an issue about a specific page by clicking the <strong>Create Issue</strong> button in the top right hand corner of the page.</p>
<h2 id="useful-resources">Useful resources</h2>
<ul>
<li><a href="https://www.docsy.dev/docs/">Docsy user guide</a>: All about Docsy, including how it manages navigation, look and feel, and multi-language support.</li>
<li><a href="https://gohugo.io/documentation/">Hugo documentation</a>: Comprehensive reference for Hugo.</li>
<li><a href="https://guides.github.com/activities/hello-world/">Github Hello World!</a>: A basic introduction to GitHub concepts and workflow.</li>
</ul>
<div class="section-index">
</div>
</div>
</main>
</div>
</div>
<footer class="bg-dark py-5 row d-print-none">
<div class="container-fluid mx-sm-5">
<div class="row">
<div class="col-6 col-sm-4 text-xs-center order-sm-2">
<ul class="list-inline mb-0">
<li class="list-inline-item mx-2 h3" data-toggle="tooltip" data-placement="top" title="User mailing list" aria-label="User mailing list">
<a class="text-white" target="_blank" rel="noopener" href="https://federated.computer/mail" aria-label="User mailing list">
<i class="fa fa-envelope"></i>
</a>
</li>
<li class="list-inline-item mx-2 h3" data-toggle="tooltip" data-placement="top" title="Twitter" aria-label="Twitter">
<a class="text-white" target="_blank" rel="noopener" href="https://twitter.com/federatedworld" aria-label="Twitter">
<i class="fab fa-twitter"></i>
</a>
</li>
</ul>
</div>
<div class="col-6 col-sm-4 text-right text-xs-center order-sm-3">
<ul class="list-inline mb-0">
<li class="list-inline-item mx-2 h3" data-toggle="tooltip" data-placement="top" title="GitHub" aria-label="GitHub">
<a class="text-white" target="_blank" rel="noopener" href="https://github.com/federatedcomputer" aria-label="GitHub">
<i class="fab fa-github"></i>
</a>
</li>
<li class="list-inline-item mx-2 h3" data-toggle="tooltip" data-placement="top" title="Developer mailing list" aria-label="Developer mailing list">
<a class="text-white" target="_blank" rel="noopener" href="https://federated.computer/developers" aria-label="Developer mailing list">
<i class="fa fa-envelope"></i>
</a>
</li>
</ul>
</div>
<div class="col-12 col-sm-4 text-center py-2 order-sm-2">
<small class="text-white">&copy; 2023 Federated Computer, Inc. All Rights Reserved</small>
<small class="ml-1"><a href="https://federated.computer" target="_blank" rel="noopener">Privacy Policy</a></small>
<p class="mt-2"><a href="/about/">About Federated Core</a></p>
</div>
</div>
</div>
</footer>
</div>
<script src="/js/main.min.8741557c571337827a7eb4977ad59c86860ae95b8e86a17138d36f059fa5fe23.js" integrity="sha256-h0FVfFcTN4J6frSXetWchoYK6VuOhqFxONNvBZ&#43;l/iM=" crossorigin="anonymous"></script>
<script src='/js/tabpane-persist.js'></script>
</body>
</html>
Reference in New Issue Copy Permalink