Merge pull request #26 from googlefonts/issue-23-restructure

Restructure/Refactor fontra docs
googlefonts · May 9, 2024 · b470172 · b470172
2 parents 7da7ec8 + e1f5742
commit b470172
Show file tree

Hide file tree

Showing 23 changed files with 233 additions and 147 deletions.
diff --git a/_config.yml b/_config.yml
@@ -5,7 +5,10 @@ baseurl: ""
 url: https://docs.fontra.xyz
 
 collections:
-  explanations:
+  introduction:
+    output: true
+    permalink: /:path/
+  tutorials:
     output: true
     permalink: /:path/
   how-tos:
@@ -14,10 +17,11 @@ collections:
   reference:
     output: true
     permalink: /:path/
-  tutorials:
+  explanations:
     output: true
     permalink: /:path/
 
+
 markdown: kramdown
 
 version: 0.1

diff --git a/_explanations/documentation.md b/_explanations/documentation.md
@@ -2,7 +2,7 @@
 title     : Documentation overview
 layout    : default
 permalink : /explanations/documentation/
-order     : 2
+order     : 901
 ---
 
 <nav aria-label="breadcrumb">
@@ -22,15 +22,17 @@ order     : 2
 - write it down as clearly as possible to pave the path for other users
 - with input from users and developers, make it better over time
 
+{% comment %}
 <div class="alert alert-warning" role="alert" markdown='1'>
 <i class="bi bi-exclamation-circle me-1"></i> Keep the docs up-to-date in relation to the app!
 {: .mb-0 }
 </div>
+{% endcomment %}
 
 ### How this documentation is structured
 
 - content is written and structured around the matrix proposed by the [Documentation System]
-- TL;DR: there are four types of documentation: *explanations*, *tutorials*, *how-tos*, *reference*
+- TL;DR: there are four types of documentation: *tutorials*, *how-tos*, *reference*, *explanations*
 - this system makes it easier for users to find what they are looking for, and for authors to expand and maintain the docs
 
 [Documentation System]: http://documentation.divio.com/
@@ -72,6 +74,8 @@ fontra-docs
 ├── _py/
 ├── css/
 ├── images/
+├── videos/
+├── _introduction/
 ├── _reference/
 ├── _explanations/
 ├── _tutorials/
@@ -105,23 +109,26 @@ css
 <div class='col-md' markdown='1'>
 ##### Content (documentation authors)
 
-reference
-: sources for pages in the *Reference* section
-
-explanations
-: sources for pages in the *Explanations* section
-
 tutorials
 : sources for pages in the *Tutorials* section
 
 how-tos
 : sources for pages in the *How-Tos* section
 
+reference
+: sources for pages in the *Reference* section
+
+explanations
+: sources for pages in the *Explanations* section
+
 index.md
 : home page of the documentation
 
 images
 : all images (screenshots, icons, etc.)
+
+videos
+: all videos
 </div>
 </div>
 
@@ -130,7 +137,9 @@ images
 #### See also
 {: .alert-heading}
 
-- [Reporting errors, suggesting changes, etc.](#)
+- [Reporting bugs, feature ideas, etc.]({{ site.url }}/how-tos/reporting)
+{% comment %}
 - [Editing the documentation](#)
+{% endcomment %}
 {: .mb-0 }
 </div>
diff --git a/_explanations/explanations.md b/_explanations/explanations.md
@@ -3,13 +3,16 @@ title     : Explanations
 layout    : default
 permalink : /explanations/
 draft     : true
-order     : 0
 ---
 
-theoretical knowledge · understanding-oriented · useful when studying
+Topics at a higher level or even from different perspectives. Explanations can equally well be described as discussions.
 {: .lead }
 
-- [Welcome to Fontra](welcome-to-fontra)
-- [Features overview](features)
-- [Documentation overview](documentation)
+- [Understanding variable components](understanding-variable-components){% comment %}order: 101{% endcomment %}
+- [Documentation overview](documentation){% comment %}order: 901{% endcomment %}
+{% comment %}
+- [Why another font editing software?](#)
+- [Why Fontra Pak](#)
+- [Plugins](#)
 - ...
+{% endcomment %}
diff --git a/_explanations/features-overview.md b/_explanations/features-overview.md
diff --git a/_explanations/understanding-variable-components.md b/_explanations/understanding-variable-components.md
@@ -0,0 +1,24 @@
+---
+title     : Understanding variable components
+layout    : default
+permalink : /explanations/understanding-variable-components/
+draft     : true
+order     : 101
+---
+
+<nav aria-label="breadcrumb">
+  <ol class="breadcrumb small">
+    <li class="breadcrumb-item"><a href="{{ site.url }}">Index</a></li>
+    <li class="breadcrumb-item"><a href="../../explanations">Explanations</a></li>
+    <li class="breadcrumb-item active" aria-current="page">{{ page.title }}</li>
+  </ol>
+</nav>
+
+<div class="__video-responsive">
+<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/Kf0B2IN7Ig8?si=fOR4KD-P5JErOqR4&amp;start=2528&end=2543" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+</div>
+
+
+### Links
+
+- [Storing Variable Components in UFO files](http://github.com/googlefonts/variable-components-in-ufo)
diff --git a/_explanations/welcome.md b/_explanations/welcome.md
diff --git a/_how-tos/create-new-glyph.md b/_how-tos/create-new-glyph.md
@@ -3,7 +3,7 @@ title     : Create new glyph
 layout    : default
 permalink : /how-tos/create-new-glyph/
 draft     : true
-order     : 6
+order     : 202
 ---
 
 <nav aria-label="breadcrumb">
@@ -14,9 +14,6 @@ order     : 6
   </ol>
 </nav>
 
-*Create new glyph* introduction
--------
-
 1. Open an existing project or start from skretch with Fontra Pak
 2. Enter the glyph you want to add to the <a href='../../reference/panels/preview-text'>**Preview text panel**</a>
 3. Double click the glyph displayed in grey and hit *create*

diff --git a/_how-tos/draw/draw-with-3-axes.md b/_how-tos/draw/draw-with-3-axes.md
@@ -0,0 +1,26 @@
+---
+title     : Draw with 3 global variations axes
+layout    : default
+permalink : /how-tos/draw/draw-with-3-axes
+draft     : true
+order     : 301
+---
+
+<nav aria-label="breadcrumb">
+  <ol class="breadcrumb small">
+    <li class="breadcrumb-item"><a href="{{ site.url }}">Index</a></li>
+    <li class="breadcrumb-item"><a href="../../how-tos">How-Tos</a></li>
+    <li class="breadcrumb-item active" aria-current="page">{{ page.title }}</li>
+  </ol>
+</nav>
+
+You will see how Gaëtan draws the word *handful* with 3 global variations axes (rounded, inktraps and pinch):
+- add axes
+- adjust spacing
+- use the multi source edition
+- interract with RoboFont for transformations (not yet implemented in Fontra)
+- Pen tool / break contours / join contours 
+
+<div class="__video-responsive">
+<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/QoGiniKFdSM?si=eXTDmaXHj_ISUrWa&amp;start=1245&end=2295" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+</div>
diff --git a/_how-tos/how-tos.md b/_how-tos/how-tos.md
@@ -3,28 +3,35 @@ title     : How-Tos
 layout    : default
 permalink : /how-tos/
 draft     : true
-order     : 0
 ---
 
-practical steps · problem-oriented · useful when working
+Solve a specific problems
 {: .lead }
 
-### Installation
+### Installation{% comment %}order: 100{% endcomment %}
 
-- [Installing Fontra Pak on your computer](installing-fontra-pak)
+- [Installing Fontra Pak on your computer](installation/installing-fontra-pak){% comment %}order: 101{% endcomment %}
+- [Installing Fontra Pak on Mac](installation/installing-fontra-pak-mac){% comment %}order: 102{% endcomment %}
+- [Installing Fontra Pak on Windows](installation/installing-fontra-pak-windows){% comment %}order: 103{% endcomment %}
+- [Building Fontra from source](installation/building-fontra-from-source){% comment %}order: 110{% endcomment %}
+{% comment %}
+- [Installing Fontra Pak on Linux](installation/installing-fontra-pak-linux)
 - Running Fontra on a web server
-- [Building Fontra from source](building-fontra-from-source)
+{% endcomment %}
 
-### Editing fonts
+### Editing fonts{% comment %}order: 200{% endcomment %}
 
-- [Opening a UFO or designspace file](opening-ufo-designspace)
-- [Creating new glyphs](create-new-glyph)
+- [Opening a UFO or designspace file](opening-ufo-designspace){% comment %}order: 201{% endcomment %}
+- [Create new glyph](create-new-glyph){% comment %}order: 202{% endcomment %}
+{% comment %}
 - Creating new glyphs at specific locations
 - Creating variable components
 - ...
+{% endcomment %}
 
-### Documentation
+### Draw{% comment %}order: 300{% endcomment %}
+- [Draw with 3 global variations axes](draw/draw-with-3-axes){% comment %}order: 301{% endcomment %}
 
-- [Keyboard Shortcuts](keyboard-shortcuts)
-- [Reporting bugs, feature ideas, etc.](reporting)
-- ...
+### Documentation{% comment %}order: 900{% endcomment %}
+
+- [Reporting bugs, feature ideas, etc.](reporting){% comment %}order: 901{% endcomment %}
diff --git a/_how-tos/building-fontra-from-source.md → ...stallation/building-fontra-from-source.md b/_how-tos/building-fontra-from-source.md → ...stallation/building-fontra-from-source.md
@@ -1,9 +1,9 @@
 ---
 title     : Building Fontra from source
 layout    : default
-permalink : /how-tos/building-fontra-from-source/
+permalink : /how-tos/installation/building-fontra-from-source/
 draft     : true
-order     : 2
+order     : 110
 ---
 
 <nav aria-label="breadcrumb">
@@ -14,5 +14,5 @@ order     : 2
   </ol>
 </nav>
 
-...
+Please go to the [Fontra Github repository](https://github.com/googlefonts/fontra) and follow the instructions written in the readme file.
 
diff --git a/_how-tos/installation/installing-fontra-pak-mac.md b/_how-tos/installation/installing-fontra-pak-mac.md
@@ -0,0 +1,29 @@
+---
+title     : Installing Fontra Pak on Mac
+layout    : default
+permalink : /how-tos/installation/installing-fontra-pak-mac/
+draft     : true
+order     : 102
+---
+
+<nav aria-label="breadcrumb">
+  <ol class="breadcrumb small">
+    <li class="breadcrumb-item"><a href="{{ site.url }}">Index</a></li>
+    <li class="breadcrumb-item"><a href="../../how-tos">How-Tos</a></li>
+    <li class="breadcrumb-item active" aria-current="page">{{ page.title }}</li>
+  </ol>
+</nav>
+
+1. [Download Fontra Pak for Mac](https://fontra-download.black-foundry.com/FontraPak.dmg)
+
+2. Unzip and double-click the package
+
+3. Then drag the Fontra Pak icon into the *Applications* folder to conclude the installation.
+
+  ![]({{ site.url }}/images/fontra-pak-installer.png){: .img-fluid}
+
+
+[Fontra Pak]: http://github.com/googlefonts/fontra-pak
+[build Fontra from source]: ../building-fontra-from-source
+[GitHub]: http://github.com
+[Actions]: http://github.com/googlefonts/fontra-pak/actions
diff --git a/_how-tos/installation/installing-fontra-pak-windows.md b/_how-tos/installation/installing-fontra-pak-windows.md
@@ -0,0 +1,33 @@
+---
+title     : Installing Fontra Pak on Windows
+layout    : default
+permalink : /how-tos/installation/installing-fontra-pak-windows/
+draft     : true
+order     : 103
+---
+
+<nav aria-label="breadcrumb">
+  <ol class="breadcrumb small">
+    <li class="breadcrumb-item"><a href="{{ site.url }}">Index</a></li>
+    <li class="breadcrumb-item"><a href="../../how-tos">How-Tos</a></li>
+    <li class="breadcrumb-item active" aria-current="page">{{ page.title }}</li>
+  </ol>
+</nav>
+
+1. [Download Fontra Pak for Windows](https://fontra-download.black-foundry.com/FontraPak.zip)
+
+2. Unzip and double-click the package
+
+3. Click 'More info'
+
+  ![]({{ site.url }}/images/fontra-pak-install-windows-1.png){: .img-fluid}
+
+4. Click 'Run anyway'
+
+  ![]({{ site.url }}/images/fontra-pak-install-windows-2.png){: .img-fluid}
+
+
+[Fontra Pak]: http://github.com/googlefonts/fontra-pak
+[build Fontra from source]: ../building-fontra-from-source
+[GitHub]: http://github.com
+[Actions]: http://github.com/googlefonts/fontra-pak/actions