Fix headings, broken image links, and ordering

Author: stickster

deployment/desktop/desktop-application-metadata-overview.md

@@ -1,20 +1,22 @@
 ---
-Title: How to package a desktop application
+title: How to package a desktop application
 subsection: desktop
-
+order: 2
 ---
 
 # {{page.title}}
 
-###System Architecture
-####Linux File Hierarchy
+### System Architecture
+#### Linux File Hierarchy
+
 Applications on Linux are expected to install binary files to /usr/bin, the install architecture independent data files to /usr/share/ and configuration files to /etc. Small temporary files can be stored in /tmp and much larger files in /var/tmp. Per-user configuration is either stored in the users home directory (in ~/.config) or stored in a binary settings store such as dconf.
 See the File Hierarchy Standard[[1](https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard)] for more information.
 
-###Desktop files
+### Desktop files
+
 Desktop files have been around for a long while now and are used by almost all Linux desktops to provide the basic description of a desktop application that your desktop environment will display. Like a human readable name and an icon. 
 
-So the creation of a desktop file on Linux allows a program to be visible to the graphical environment, e.g. KDE or GNOME Shell. If applications do not have a desktop file they must be manually launched using a terminal emulator. Desktop files must adhere to the Desktop File Specification[[2](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#introduction) ] and provide metadata in an ini-style format such as:
+So the creation of a desktop file on Linux allows a program to be visible to the graphical environment, e.g. KDE or GNOME Shell. If applications do not have a desktop file they must be manually launched using a terminal emulator. Desktop files must adhere to the Desktop File Specification[[2](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#introduction)] and provide metadata in an ini-style format such as:
 
 - Binary type, typically ‘Application’
 - Program name (optionally localized)
@@ -55,7 +57,8 @@ This tools is available through the desktop-file-utils package, which you can in
 
 	dnf install desktop-file-utils
 
-###AppData Files
+### AppData Files
+
 At least one valid AppData file with the suffix .appdata.xml file should be installed into /usr/share/appdata with a name that matches the name of the .desktop file, e.g. gimp.desktop & gimp.appdata.xml or org.gnome.Nautilus.desktop & org.gnome.Nautilus.appdata.xml.
 
 In the AppData file you should include several 16:9 aspect screenshots along with a compelling translated description made up of multiple paragraphs. 
@@ -121,21 +124,22 @@ A typical (albeit somewhat truncated) AppData file is shown below:
 	  <translation type="gettext">gnome-multi-writer</translation>
 	</component>
 
-####Some Appstream background
+#### Some Appstream background
 
 The AppStream specification is a mature and evolving standard that allows upstream applications to provide metadata such as localized descriptions, screenshots, extra keywords and content ratings for parental control. The basic concept is that the upstream project ships one extra AppData XML file which is used to build a global application catalog called an AppStream file. Over 1000 open source projects now include AppData files, and the software center shipped in Fedora, Ubuntu and OpenSuse is an easy-to-use application filled with useful application metadata. Applications without AppData files are no longer shown which provides quite some incentive to upstream projects wanting visibility in popular desktop environments.
 
 The AppStream specification is an mature and evolving standard that allows upstream applications to provide metadata such as localized descriptions, screenshots, extra keywords and content ratings for parental control. The basic concept is that the upstream project ships one extra AppData XML file which is used to build a global application catalog called an AppStream file. Over 1000 open source projects now include AppData files, and the software center shipped in Fedora, Ubuntu and OpenSuse is now an easy to use application filled with useful application metadata. Applications without AppData files are no longer shown which provides quite some incentive to upstream projects wanting visibility in popular desktop environments.
 
-AppStream[[3](https://www.freedesktop.org/software/appstream/docs/) ] was first introduced in 2008 and since then many people have contributed to the specification. It is being used primarily for application metadata but also now is used for drivers, firmware, input methods and fonts. There are multiple projects producing AppStream metadata and also a number of projects consuming the final XML metadata.
+AppStream[[3](https://www.freedesktop.org/software/appstream/docs/)] was first introduced in 2008 and since then many people have contributed to the specification. It is being used primarily for application metadata but also now is used for drivers, firmware, input methods and fonts. There are multiple projects producing AppStream metadata and also a number of projects consuming the final XML metadata.
 
 When applications are being built as packages by a distribution then the AppStream generation is done automatically, and you do not need to do anything other than installing a .desktop file and an appdata.xml file in the upstream tarball or zip file.
 
 If the application is being built on your own machines or cloud instance then the distributor will need to generate the AppStream metadata manually. This would for example be the case when internal-only or closed source software is being either used or produced. This document assumes you are currently building RPM packages and exporting yum-style repository metadata for Fedora or RHEL although the concepts are the same for rpm-on-OpenSuse or deb-on-Ubuntu.
 
 NOTE: If you are building packages, make sure that there are not two applications installed with one single package. If this is currently the case split up the package so that there are multiple subpackages or mark one of the .desktop files as NoDisplay=true. Make sure the application-subpackages depend on any -common subpackage and deal with upgrades (perhaps using a metapackage) if you’ve shipped the application before.
 
-###Summary of Package building
+### Summary of Package building
+
 The steps outlined above explain the extra metadata that you need for your application to show up in GNOME Software. This tutorial does not cover how to set up your build system to build these, but both for  Meson and autotools you should be able to find a plethora of examples online. 
 And there are also major resources available to explain how to create a [Fedora RPM](https://fedoraproject.org/wiki/How_to_create_an_RPM_package) or [how to build a Flatpak](http://docs.flatpak.org/en/latest/). You probably also want to tie both the Desktop file and the AppData file into your i18n system so the metadata in them can be translated.
 
@@ -146,11 +150,9 @@ And there are also major resources available to explain how to create a [Fedora
 
 It is worth nothing here that while this document explains how you can do everything yourself we do generally recommend relying on existing community infrastructure for hosting source code and packages if you can (for instance if your application is open source), as they will save you work and effort over time. For instance putting your sourcecode into the GNOME git will give you free access to the translator community in GNOME and thus increase the chance your application is internationalized significantly. And by building your package in Fedora you can get peer review of your package and free hosting of the resulting package. We are also working on a service that will automatically generate a Flatpack bundle of your application in Fedora, meaning you get a Flatpak version of your application for free as a result.
 
-###Citations
+### Citations
 
 1. [Filesystem Hierarchy Standard: 17th October 2016](https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard) 
 2. [Desktop Specification: 17th October 2016](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#introduction) 
 3. [AppStream Specification 0.10: 17th October 2016](https://www.freedesktop.org/software/appstream/docs/) 
 4. [SPDX license list](https://spdx.org/licenses/)
-
-[Back to index](how-to-package-a-desktop-application.md) 

deployment/desktop/desktop-software-hosting.md

@@ -1,18 +1,21 @@
 ---
 title: How to Host Desktop Software
 subsection: desktop
-
+order: 3
 ---
 
 # {{page.title}}
 
-##Setting up hosting infrastructure for your package
+## Setting up hosting infrastructure for your package
+
 We will here explain how you set up a Yum repository for RPM packages that provides the needed metadata. If you are making a Flatpak we recommend skipping ahead to the Flatpak section a bit further down.
 
-###Yum hosting and metadata
+### Yum hosting and metadata
+
 When GNOME Software checks for updates it downloads various metadata files from the server describing the packages available in the repository. GNOME Software can also download AppStream metadata at the same time, allowing add-on repositories to include applications that are visible in the software center.
 
-###Yum hosting and Metadata:
+### Yum hosting and Metadata:
+
 When GNOME Software checks for updates it downloads various metadata files from the server describing the packages available in the repository. GNOME Software can also download AppStream metadata at the same time, allowing add-on repositories to include applications that are visible in the the software center.
 
 In most cases distributors are already building binary RPMS and then building metadata as an additional step by running something like this to generate the repomd files on a directory of packages. The tool for creating the repository metadata is called createrepo_c and is part of the package createrepo_c in Fedora. You can install it by running the command:

deployment/desktop/how-to-host-yum-repo-on-github.md

@@ -1,12 +1,13 @@
 ---
 title: Hosting a Yum Repository on Github
 subsection: desktop
-
+order: 4
 ---
 
 # {{page.title}}
 
-####Hosting your Yum repository on Github
+#### Hosting your Yum repository on Github
+
 Github isn't really set up for hosting Yum repositories, but here is a method that currently works. So once you created a local copy of your repository create a new project on github. Then use the follow commands to import your repository into github.
 
 	cd ~/src/myrepository
@@ -32,5 +33,5 @@ Copy that URL as you will need the information from it to create your .repo file
 So on top is your Repo shortname inside the brackets, then a name field with a more extensive name. For the baseurl paste the URL you copied earlier and remove the last bits until you are left with either the 'norach' directory or your platform directory for instance x86_64.
 
 Once you have that file completed put it into /etc/yum.repos.d on your computer and load up GNOME Software. Click on the 'Updates' button in GNOME Software and then on the refresh button in the top left corner to ensure your database is up to date. If everything works as expected you should then be able to do a search in GNOME software and find your new application showing up.
-![Example GNOME Software listing](example-gnome-software-listing.png  "Example GNOME Software listing")
+![Example GNOME Software listing](/content/deployment/desktop/example-gnome-software-listing.png  "Example GNOME Software listing")
 

deployment/desktop/how-to-package-a-desktop-application.md

@@ -2,41 +2,47 @@
 title: Adding Applications to GNOME Software
 section: deployment
 subsection: desktop
-
+description: >
+  How to build, package, and host your applications so they show up in GUI desktop tools for easy deployment by your users.
 order: 1
 ---
 
 # {{page.title}}
 
 **Written by Richard Hughes and Christian F.K. Schaller**
 
-##Abstract
+## Abstract
 
 Traditionally we have had little information about Linux applications before they have been installed. With the creation of a software center we require access to rich set of metadata about an application before it is deployed so it it can be displayed to the user and easily installed.
 This document is meant to be a guide for developers who wish to get their software appearing in the Software stores in Fedora Workstation and other distributions. Without the metadata described in this document your application is likely to go undiscovered by many or most linux users, but by reading this document you should be able to relatively quickly prepare you application.
 
-![GNOME Software](steam-gnome-software.png  "Example of Steam listing in GNOME Software")
+![GNOME Software](/content/deployment/desktop/steam-gnome-software.png  "Example of Steam listing in GNOME Software")
 
-###Introduction to the technical details
+### Introduction to the technical details
 
 Installing applications on Linux has traditionally involved copying binary and data files into a directory and just writing a single desktop file into a per-user or per-system directory so that it shows up in the desktop environment.  In this document we refer to applications as graphical programs, rather than other system add-on components like drivers and codecs. This document will explain why the extra metadata is required and what is required for an application to be visible in the software center. We will try to document how to do this regardless of if you choose to pakcage your application as a rpm package or as a flatpak bundle. The current rules is a combination of various standards that have evolved over the years and will will try to summarize and explain them here, going from bottom to top. 
 
-1. An introduction to [Desktop Application metadata](desktop-application-metadata-overview.md) 
+1. An introduction to [Desktop Application metadata](desktop-application-metadata-overview.html)
+
+2. Special steps to [ setup and create desktop yum repo](desktop-software-hosting.html) 
 
-2. Special steps to [ setup and create desktop yum repo](desktop-software-hosting.md) 
+3. Instructions for [how to host a Yum repo on github](how-to-host-yum-repo-on-github.html)
 
-3. Instrunctions for  [how to host a Yum repo on github](how-to-host-yum-repo-on-github.md) 
+4. How to [setup and host flatpaks](how-to-setup-and-host-flatpaks.html)
 
-4. How to [setup and host flatpaks](how-to-setup-and-host-flatpaks.md) 
+5. How to [propose third party software for Fedora listing](how-to-propose-a-3rd-party-application-for-inclusion-in-fedora.html)
 
-5. How to  [Propose 3rd party Software for Fedora listing](how-to-propose-a-3rd-party-application-for-inclusion-in-fedora.md) 
 
+### Summary
 
-###Summary
 AppStream files allow us to build a modern software center experience either using legacy distro packages with yum-style metadata or with the new flatpak application deployment framework. By including a desktop file and AppData file for your Linux binary build your application can be easily installed by end users.
-###Future Work
+
+### Future Work
+
 AppData currently uses the OARS content rating system which will be expanded for more uses cases and filtering options.
-###	Related Work
+
+### Related Work
+
 The ODRS[1] is a web service which provides end-user moderated application reviews using the AppStream application ID.
 
 

deployment/desktop/how-to-propose-a-3rd-party-application-for-inclusion-in-fedora.md

@@ -1,12 +1,13 @@
 ---
 title: Propose a Third Party App to Include in Fedora
 subsection: desktop
-
+order: 6
 ---
 
 # {{page.title}}
 
-###Getting it into Fedora Workstation
+### Getting it into Fedora Workstation
+
 You now have your repository created and ready for users to connect to it. The final step is getting your repository added to Fedora Workstation.
 To start the process for this you can file a [Fedora ticket](https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora) against the Fedora-workstation-repositories component. The information needed is a decription of your application. We also need the URL where the repository is located.
 

deployment/desktop/how-to-setup-and-host-flatpaks.md

@@ -1,12 +1,12 @@
 ---
 title: Set Up and Host Flatpaks
 subsection: desktop
-
+order: 5
 ---
 
 # {{page.title}}
 
-###Flapak hosting and Metadata
+### Flatpak hosting and Metadata
 
 The flatpak-builder binary generates AppStream metadata automatically when building applications if the appstream-compose tool is installed on the flatpak build machine. Flatpak[1] repositories are exported with a separate ‘appstream’ branch which is automatically downloaded by GNOME Software and no additional work is required when building your application or updating the remote. Adding the remote is enough to add the application to the software center, on the assumption the AppData file is valid.
 
@@ -42,6 +42,7 @@ The best way to make your application and its Flatpak repository available to us
 	Comment=GNOME loves to cook
 
 ### Hosting a Flatpak repository on Github
+
 Github isn't really set up for hosting Flatpak repositories, so we can't guarantee that this will keep working in the future. So once you created a local copy of your repository create a new project on github, enable github pages for the project and point it at the master branch.
 Then use the follow commands to import your repository into github.