Nift Tutorial

Tutorial to get a better understanding of how Nift works

The following tutorial will help you learn how Nift works, if you are just taking a look at Nift you may prefer the getting started guide 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 or here.

  1. 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);
  2. 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);
  3. 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;
  4. 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;
  5. If you ever forget a Nift command, enter nsm commands into your terminal window;
  6. Enter nsm status into your terminal window;
  7. Enter nsm info-all, nsm info-names and nsm status;
  8. 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;
  9. We will come back to building pages later in the tutorial, but enter nsm build-updated.
  10. The page list file .siteinfo/pages.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
    		    
    		    							

  11. Enter nsm info-all, nsm info-names, nsm info about, nsm info about index and nsm status;
  12. Enter nsm rm first_page and repeat the last step;
  13. Enter nsm build-updated;
    • The directory site/ should now contain the pages index.html, about.html and first_page.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 .siteinfo/site/ should have been created containing the info files index.info, about.info and first_page.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;
  14. Open site/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 site/index.html
  15. Enter nsm status;
  16. Modify content/index.content;
  17. Enter cd content/;
  18. 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);
  19. Enter cd ../ to change back to the stage directory;
  20. Modify template/footer.content;
  21. Enter nsm status, then nsm build-updated;
  22. Add @input(content/badfile.content) to content/index.content;
  23. Enter nsm status, then nsm build-updated, then nsm status;
  24. Replace @input(content/badfile.content) with @input(content/index.content) in content/index.content;
  25. Enter nsm status, then nsm build-updated, then nsm status;
  26. Remove @input(content/index.content) from content/index.content;
  27. Enter nsm status, then nsm build-updated;
  28. Add \$x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}\$ to content/about.content;
  29. Enter nsm build-updated and reload site/about.html;
  30. Add the following to content/about.content;
    		    								<pre>
    		    									ostream& operator<<(ostream &os, const std::vector<std::string> &v)
    		    									{
    		    										if(v.size())
    		    											os << v[i];
    		    										for(auto i=1; i<v.size(); i++)
    		    											os << " " << v[i];
    		    										return os;
    		    									}
    		    								</pre>
    		    							

  31. Enter nsm build-updated and reload site/about.html. View the source for site/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 site/about.html and see what happens when you revert back to using < inside the pre tags);
  32. Remove @jsinclude(site/js/process_pre_tags.js) from templates/page.template;
  33. Enter nsm build-updated and reload site/about.html. Notice how the code block now has unwanted indenting? All whitespace is preserved between pre tags, which is where process_pre_tags.js comes in. For each pre block the script finds how many leading tabs the second line has (ie. the line after the pre block is opened), then strips that number of leading tabs from each line in the block. Alternatively users could just have horribly indented source code, personally I prefer this;

    Note: indenting of pre blocks must be tabs (indenting inside pre blocks can still be any combination of tabs/spaces). One can alter the js to also look for spaces,or just spaces, however it will still be stripping the indenting of the second line from the remaining lines, if you wanted to allow for inconsistent combinations of tabs/spaces for indenting inside code blocks you would also need to fix tab width using css, which would still be broken for users who use a different tab width and use inconsistent indenting. Do not just do a global replacement of tabs or four spaces either, yes it will fix indenting of pre blocks, but it may mess up indenting inside pre blocks when pages are displayed in a browser, and will infuriate users trying to work out why;
  34. Add @jsinclude(site/js/process_pre_tags.js) back to the end of the body in templates/page.template
  35. Now try changing the open pre tag in content/about.content from <pre> to <pre class="inline rounded prettyprint lang-cpp">.
  36. Enter nsm build-updated and reload site/about.html. See site/css/pre.css for how the simple site styles pre blocks.
  37. Enter nsm mv about test, check that: .siteinfo/pages.list has been updated; both site/index.html and .siteinfo/site/index.info were removed; and content/about.content was moved to content/test.content;
  38. Enter nsm cp test about, check that .siteinfo/pages.list has been updated and content/test.content was copied to content/about.content;
  39. Enter nsm rm test, check that content/test.content, site/test.html and .siteinfo/site/test.info were all removed.
  40. Enter nsm untrack index, check that both site/index.html and .siteinfo/site/index.info were removed.
  41. 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.