Managing Projects and Versions

Tidal supports multiple projects and versions. Projects are created and managed via. the control panel, and versions can be easily managed from the command line.

#Creating Projects

New projects you'd like to document can be added within the Statamic control panel.

Existing projects may be managed from the "Software Projects" collection; this collection is orderable, and the order of projects will be used on the default home page.

Clicking "Create Entry" will display the create project page:

The highlighted fields should be entered when first creating your project:

• Title: The name of your software project.

• Slug: The default slug for your software project. This is not necessarily used for routing individual documentation pages.

• Project Description: A user-friendly description of the software project. This is displayed on the default home page.

The project screen also contains these additional fields:

• Show Version Warning: Controls whether the "you are viewing an older version" warning displays when a user visits older versions on your site.

• Project Versions: Allows you to manage the versions of your software project. It is highly recommended that new versions be added from the command line. The order, details, and version-specific settings can be managed from the Control Panel, however.

#Creating Versions

Each software project within a Tidal site needs at least one version. A version contains additional settings, as well as the entries for each of the documentation pages. Each version within a project has a few components to make everything work:

• Dedicated Collection: Each version's contents are managed in its own dedicated ordered collection. The collection's route settings control the front-end routing per version.

• Project Version Entry: Each version must also be listed within a single project's "Project Versions" field.

All required collections and project version field updates are handled for you by the command line utility. To use the version utility run the following command from the root of your project:

1php artisan tidal:create-version

The tidal:create-version command does not accept any arguments and will prompt you to answer a variety of questions to create your new project version.

The first thing the utility will prompt you for is the project to add the version to:

1php artisan tidal:create-version
2  Select a project to add a version to.
3  Example Project .................................. 0
4  Tidal ............................................ 1
5❯

After entering a project to add a version to the utility will list all existing versions for your reference:

 1❯ 1
 2
 3Gathering information for Tidal...
 4Tidal has the following versions:
 5+--------------+--------+
 6| Version Name | Number |
 7+--------------+--------+
 8| Alpha        | 0.0.0  |
 9| 1.x          | 1.0.0  |
10+--------------+--------+
11
12 What is the name of the new version?:
13 >

The next prompt is "What is the name of the new version?". A version name is displayed on the site in the version selection, in the case of multiple versions. The version name should be short and representative of the version you wish to document.

After entering a version name you will be prompted to enter the version number:

1What is the name of the new version?:
2> Beta
3
4What is the version number?:
5>

The version number is the numeric representation of your version name. It is primarily used by the create-version utility to automatically sort your project's versions for you.

Once we've supplied a version number we will be asked to supply the handle of the documentation collection. Don't worry if it a collection for this new version doesn't already exist (this process is actually easier if it doesn't):

If the collection is not found, you will be asked if you'd like the utility to automatically create it for you. It is highly recommended you create new version collections using this utility, as it adds a number of blueprints and required configuration settings for you:

1What is the version number?:
2> 0.5.0
3
4What is the handle of the documentation collection?:
5> tidal_beta_docs
6
7Collection not found. Would you like to create it? (yes/no) [yes]:
8>

Enter yes to continue creating the collection. You will be prompted for the following information to create the collection:

• The collection title: enter a title that makes it clear what the collection's purpose is. In our current example, a good title might be "Tidal Beta Documentation"

• The collection route: the route pattern to use for the new collection. Each version's collection manages its own route pattern, allowing for incredible flexibility in how you structure your documentation website. A recommended route pattern is project-name/version-name/{slug}. For our current example I will use tidal/beta/{slug}.

 1 Collection not found. Would you like to create it? (yes/no) [yes]:
 2 > yes
 3
 4 What is the title for the new collection?:
 5 > Tidal Beta Documentation
 6
 7 What would you like the route to be? You should keep it simple, like "project-name/v2/{slug}".:
 8 > tidal/beta/{slug}
 9
10Creating collection...
11Collection created.
12Creating blueprints...
13Adding version to project...
14Version added to project.
15Don't forget to add the version to your search, sitemap, or social media image config!

After answering all of the prompts we can now visit the Statamic control panel to view our newly created version:

#Configuration Updates

After a version has been created there are a few additional (and optional) configuration updates you might wish to make.

• config/social_media_image_kit/genera.php: You may wish to add your new collection to the collections configuration item. This will enable social media images on your new collection.

• config/feedamic.php: You can add your new collection to the default documentation feed; this will add your new documentation collection to your site's RSS/Atom feeds.

• config/statamic/search.php: If you'd like your new documentation search to be added to the documentation search, you can add it to the doc.searchables configuration option.