Skip to content

philosophy.md

Latest commit

 

History

History
382 lines (251 loc) · 8.86 KB

philosophy.md

File metadata and controls

382 lines (251 loc) · 8.86 KB
nav_order 4
title Philosophy
nav_exclude true

Freelancing needs a platform

Some things should be free...

... and the other things should be optional

It's simple of use, free and fair to both parties. {: .fs-6 .fw-300 }

Introductionc

Navigation Structure

{: .no_toc }

Table of contents

{: .no_toc .text-delta }

  1. TOC {:toc}

GitHub Logo

Freelancing needs a Protocol enables freelancers and their clients to trade deliverable against payment, outside of freelancer platforms. It is simple of use, free and fair to both parties.

Freelancing needs a protocol

{: .fs-9 }

Get started now{: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 } View it on GitHub{: .btn .fs-5 .mb-4 .mb-md-0 }

---## In a nutshell

Lifecycle of a milestone

A milestone starts when both parties accept its terms.

Getting started

  1. Toc

Dependencies

Just the Docs is built for Jekyll, a static site generator. View the quick start guide for more information. Just the Docs requires no special plugins and can run on GitHub Pages' standard Jekyll compiler. The Jekyll SEO Tag plugin is included by default (no need to run any special installation) to inject SEO and open graph metadata on docs pages. For information on how to configure SEO and open graph metadata visit the Jekyll SEO Tag usage guide.

Quick start: Use as a GitHub Pages remote theme

  1. Add Just the Docs to your Jekyll site's _config.yml as a remote theme
remote_theme: pmarsceill/just-the-docs

You must have GitHub Pages enabled on your repo, one or more Markdown files, and a _config.yml file. See an example repository

Local installation: Use the gem-based theme

  1. Install the Ruby Gem
$ gem install just-the-docs
# .. or add it to your your Jekyll site’s Gemfile
gem "just-the-docs"
  1. Add Just the Docs to your Jekyll site’s _config.yml
theme: "just-the-docs"
  1. Optional: Initialize search data (creates search-data.json)
$ bundle exec just-the-docs rake search:init
  1. Run you local Jekyll server
$ jekyll serve
# .. or if you're using a Gemfile (bundler)
$ bundle exec jekyll serve
  1. Point your web browser to http://localhost:4000

If you're hosting your site on GitHub Pages, set up GitHub Pages and Jekyll locally so that you can more easily work in your development environment.

Configure Just the Docs

About the project

Just the Docs is © 2017-2019 by Patrick Marsceill.

License

Just the Docs is distributed by an MIT license.

Contributing

When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change. Read more about becoming a contributor in our GitHub repo.

Thank you to the contributors of Just the Docs!

    {% for contributor in site.github.contributors %}
  • {{ contributor.login }}
    • {% endfor %}

Code of Conduct

Just the Docs is committed to fostering a welcoming community.

View our Code of Conduct on our GitHub repository.

Navigation Structure

{: .no_toc }

Table of contents

{: .no_toc .text-delta }

  1. TOC {:toc}

Main navigation

The main navigation for your Just the Docs site is on the left side of the page at large screens and on the top (behind a tap) on small screens. The main navigation can be structured to accommodate a multi-level menu system (pages with children and grandchildren).

By default, all pages will appear as top level pages in the main nav unless a parent page is defined (see Pages with Children).

Ordering pages

To specify a page order, use the nav_order parameter in your pages' YAML front matter.

Example

{: .no_toc }

---
layout: default
title: Customization
nav_order: 4
---

Excluding pages

For specific pages that you do not wish to include in the main navigation, e.g. a 404 page or a landing page, use the nav_exclude: true parameter in the YAML front matter for that page.

Example

{: .no_toc }

---
layout: default
title: 404
nav_exclude: true
---

Pages with children

Sometimes you will want to create a page with many children (a section). First, it is recommended that you keep pages that are related in a directory together... For example, in these docs, we keep all of the written documentation in the ./docs directory and each of the sections in subdirectories like ./docs/ui-components and ./docs/utilities. This gives us an organization like:

+-- ..
|-- (Jekyll files)
|
|-- docs
|   |-- ui-components
|   |   |-- index.md  (parent page)
|   |   |-- buttons.md
|   |   |-- code.md
|   |   |-- labels.md
|   |   |-- tables.md
|   |   +-- typography.md
|   |
|   |-- utilities
|   |   |-- index.md      (parent page)
|   |   |-- color.md
|   |   |-- layout.md
|   |   |-- responsive-modifiers.md
|   |   +-- typography.md
|   |
|   |-- (other md files, pages with no children)
|   +-- ..
|
|-- (Jekyll files)
+-- ..

On the parent pages, add this YAML front matter parameter:

  • has_children: true (tells us that this is a parent page)

Example

{: .no_toc }

---
layout: default
title: UI Components
nav_order: 2
has_children: true
---

Here we're setting up the UI Components landing page that is available at /docs/ui-components, which has children and is ordered second in the main nav.

Child pages

{: .text-gamma }

On child pages, simply set the parent: YAML front matter to whatever the parent's page title is and set a nav order (this number is now scoped within the section).

Example

{: .no_toc }

---
layout: default
title: Buttons
parent: UI Components
nav_order: 2
---

The Buttons page appears as a child of UI Components and appears second in the UI Components section.

Auto-generating Table of Contents

By default, all pages with children will automatically append a Table of Contents which lists the child pages after the parent page's content. To disable this auto Table of Contents, set has_toc: false in the parent page's YAML front matter.

Example

{: .no_toc }

---
layout: default
title: UI Components
nav_order: 2
has_children: true
has_toc: false
---

Children with children

{: .text-gamma }

Child pages can also have children (grandchildren). This is achieved by using a similar pattern on the child and grandchild pages.

  1. Add the has_children attribute to the child
  2. Add the parent and grand_parent attribute to the grandchild

Example

{: .no_toc }

---
layout: default
title: Buttons
parent: UI Components
nav_order: 2
has_children: true
---

---
layout: default
title: Buttons Child Page
parent: Buttons
grand_parent: UI Components
nav_order: 1
---

This would create the following navigation structure:

+-- ..
|
|-- UI Components
|   |-- ..
|   |
|   |-- Buttons
|   |   |-- Button Child Page
|   |
|   |-- ..
|
+-- ..

Auxiliary Navigation

Example

{: .no_toc }

# Aux links for the upper right navigation
aux_links:
  "Just the Docs on GitHub":
    - "//github.com/pmarsceill/just-the-docs"

In-page navigation with Table of Contents

To generate a Table of Contents on your docs pages, you can use the {:toc} method from Kramdown, immediately after an <ol> in Markdown. This will automatically generate an ordered list of anchor links to various sections of the page based on headings and heading levels. There may be occasions where you're using a heading and you don't want it to show up in the TOC, so to skip a particular heading use the {: .no_toc } CSS class.

Example

{: .no_toc }

# Navigation Structure

{: .no_toc }

## Table of contents

{: .no_toc .text-delta }

1. TOC
   {:toc}

This example skips the page name heading (#) from the TOC, as well as the heading for the Table of Contents itself (##) because it is redundant, followed by the table of contents itself.