News:Modular Install Guide Parts

Modular Install Guide Parts

The Install Guide is now modular. Learn how it works, and how you can use it to create your own customized Install Guides.

By Drobbins / November 12, 2014

Hello, everyone! I wanted to tell you a bit about our new modular Installation Guide, and explain how it works, and how you can use it to create and maintain your own customized Installation Guide.

One of the issues we have had with our install instructions is that often, people like to create their own variant install guides. In fact, we do this quite a bit ourselves, such as with the UEFI Install Guide and the ZFS Install Guide. Our approach generally has been that the variant install guides cover only the differences between our official Funtoo Linux Installation page, which serves as our official reference. The problem with this approach is that it is sometimes inflexible and it can be nice to have a fully complete variant installation guide, too.

But, we also have the problem with variant installation guides not getting maintained and updated. So just having an entirely separate document that covers all the installation steps is also impractical. Jonathan Harker filed FL-1752 suggesting that this is an issue that needs to get fixed.

The solution to these problems is the new modular install guide parts. You can view all the install guide parts here: Category:Installation Guide Parts.

Each install guide part is a template, which is meant to be included in an official Install Guide using the following syntax:

{{:Install/PartName}}

This template call, above, will result in that particular install guide part appearing in the install guide. As updates are made to this part, they will automatically appear in all install guides that use it.

   Note

If you are somewhat familiar with MediaWiki wikitext, you may still not have seen a template call that is prefixed with a colon. Most template calls are not prefixed with a colon, and they automatically refer to templates in the Template namespace. On the Funtoo wiki, the template namespace is locked down so that regular users cannot edit it, so I've placed the install guide parts in the Main (default) namespace. To expand a template in the Main namespace, an initial colon is used. Also note that the slash in the template call is used to refer to a subpage -- in this case, a subpage of the Install wiki page (which is currently unused, but may eventually be the official home for our Install Guide.)

Creating your own Install Guide

To create your own customized Install Guide, you will want to copy the wikitext contained on the Funtoo Linux Installation page. You'll notice that this wikitext is basically all template calls to the various Install Guide Parts.

For the parts that you want to modify, simply delete the template call, and insert your literal wikitext into your install guide. For all other sections that should stay the same as the original install guide, keep the template calls. When you save your new install guide, you'll notice that it's complete. The benefits of this approach is that your guide will automatically benefit from improvements to the install guide parts as they are maintained by the Funtoo Linux user community.

Enjoy the new functionality!