Nift - basic

The following tutorial will help you learn the basic usage of Nift, if you are just taking a look at Nift you may prefer the get started tutorial which will get you up and running much quicker, then come back when you want to have a better understanding of how Nift works.

The easiest way to learn how Nift works is to get your feet wet and hands dirty playing with a simple site. If there is any problems with the following tutorial please file an issue here.

Download simple-site-master.zip and extract simple-site-master. If you have a BitBucket, GitHub and/or GitLab account then you can import/fork and rename a repository from here, here or here then clone using nsm clone repository-url (Note - You can rename a repository when importing it, rather than forking and renaming, plus on BitBucket and GitHub you cannot remove fork relationships);
If you imported/forked a repository on GitHub then in the repository's settings on GitHub for GitHub Pages set the source to master branch (there may be some delay before your website goes live);
Open a terminal window and change to the simple-site-master directory, you will also find it useful to have the simple-site-master directory open using your operating system's window manager;
Open template/page.template, template/footer.content, template/menu.content, content/index.content and content/about.content in any text editor you like, take a look at what each file contains;
If you ever forget a Nift command, enter nsm commands into your terminal window;
Enter nsm status into your terminal window;
Enter nsm info-all, nsm info-names and nsm status;
The command to have Nift track a page is nsm track page-name page-title template-path, where page-title and template-path are optional (default page-title is the specified page-name, and default template-path is template/page.template). Enter nsm track first_page myPageTitle;
We will come back to building pages later in the tutorial, but enter nsm build-updated.

The page list file .nsm/tracking.list should now contain the following information for pages about and index;

'about'
'about'
'template/page.template'

'first_page'
'myPageTitle'
'template/page.template'

'index'
'home'
'template/page.template'

Enter nsm info-all, nsm info-names, nsm info about, nsm info about index and nsm status;
Enter nsm rmv first_page and repeat the last step;
Enter nsm build-updated;
- The directory output/ should now contain the pages index.html and about.html. By default users do not have permission to write to page files, this is to prevent users from accidentally modifying a page file when they more than likely intended to modify a content file. Should users want to manually edit a page file they can simply change the file permissions (eg. chmod +w page-path);
- Another directory .nsm/output/ should have been created containing the info files index.info and about.info. By default users do not have permission to write to info files, and users should beware of ever doing so. The modification time of info files is how Nift knows when pages were last built (actually I am pretty sure Nift gets this information from the first line of the information files), furthermore the content inside info files represents page dependencies from the last time pages were built, not necessarily current page dependencies, hence users should not have any reason to modify them;
Open output/index.html in a browser, click through to the about page, and view the source for both pages. Compare what you have locally to a pre-built version of output/index.html
Enter nsm status;
Modify content/index.content;
Enter cd content/;
Enter nsm status, then nsm build-updated, then nsm status (notice Nift can be run from any directory inside the stage directory, stage directory inclusive, obviously as that is where we started! If you are using BitBucket or GitHub then the site directory is set up as a master branch);
Enter cd ../ to change back to the stage directory;
Modify template/footer.content;
Enter nsm status, then nsm build-updated;
Add @input(content/badfile.content) to content/index.content;
Enter nsm status, then nsm build-updated, then nsm status;
Replace @input(content/badfile.content) with @input(content/index.content) in content/index.content;
Enter nsm status, then nsm build-updated, then nsm status;
Remove @input(content/index.content) from content/index.content;
Enter nsm status, then nsm build-updated;
Add $x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$ to content/about.content;
Enter nsm build-updated and reload output/about.html;

Add the following to content/about.content without any indenting;

<pre>
ostream& operator<<(ostream &os, const std::vector<std::string> &v)
{
	if(v.size())
		os << v[0];
	for(auto i=1; i<v.size(); i++)
		os << " " << v[i];
	return os;
}
</pre>

Enter nsm build-updated and reload output/about.html. View the source for output/about.html and look at the text inside the pre tags. Notice how every < character has been escaped to \<, Nift automatically does this so you can simply paste your code straight into content files, otherwise you would need to manually replace < characters (if you want, add write permissions to output/about.html and see what happens when you revert back to using < inside the pre tags);
Now try changing the open pre tag in content/about.content from <pre> to <pre class="inline rounded prettyprint">.
Enter nsm build-updated and reload output/about.html. See output/css/pre.css for how the simple site styles pre blocks.
Enter nsm mve about test, check that: .nsm/tracking.list has been updated; both output/about.html and .nsm/output/about.info were removed; and content/about.content was moved to content/test.content;
Enter nsm cpy test about, check that .nsm/tracking.list has been updated and content/test.content was copied to content/about.content;
Enter nsm rmv test, check that content/test.content, output/test.html and .nsm/output/test.info were all removed.
Enter nsm untrack index, check that both output/index.html and .nsm/output/index.info were removed.
If you forked, renamed and cloned a repository from BitBucket, GitHub or GitLab then you can build, commit and push changes back to BitBucket, GitHub or GitLab all at the same time using nsm bcp "commit message" (note for BitBucket you will need to enter your password twice and for GitHub you will need to enter your username and password twice, this is because of using both a stage and master branch for BitBucket/GitHub, something which is not done for GitLab). There may be some delay before your changes go live.