Web content projects typically exist in multiple states: edited, committed, staged, and deployed. Here is a very brief explanation of content management:
Editing is work in progress, where changes are not yet a part of a repository. When completed, the developer commits work to his local repository. Periodically a developer will synchronize his local work with a master repository, and then push his commits to be merged into that master. When the master repository contains a complete, working version of the project, the project will be deployed to the web.
The developer needs to test the results of his local work in progress, before and after committing to his local repository. The merged work of the entire project needs to be staged and reviewed. Finally, the current deployed product needs to be viewed for comparison during development.
The reader may be thinking, “I never had to do all that with _(insert a CMS package name here)_.” If so, the reader is not a developer (yet).
cd ~/Projects/doc-firsttask
kate firstdoc.rst
The extension .rst identifies restructured text documents. Make Kate the default editor for this document type.
Use the notations for text structure to markup text. Start each document of the project with a heading, and go on from there.
Open the Interactive rST Editor in a browser tab, and paste text into the left pane. Interpreted HTML output will display on the right.
In a browser tab, substitute your username and the name of your project folder into the following URL to see the index of files in a local project, and to view the output of individual documents:
file:///home/__username__/Projects/__projectfolder__/_build/html/index.html
What should never have to be said, must be said.
Make git aware of current changes with the command:
git add .
The “dot” means track everything in a project directory. Name specific files if everything is not desired. Exclude categories of files from tracking with entries in .gitignore, as previously shown.
git status
Shows what git has staged to be committed based on add commands.
Always use git to move or rename a tracked file. The syntax is the same as Linux mv command, but proceded with git:
git mv old_filename.rst new_filename.rst
As with moving a tracked file, use a git command when deleting:
git rm bad_filename.rst
Periodically add and commit completed content to your local repository:
git add .
git status
git commit -m "type a brief message here describing your changes"
Before starting a day’s work, synchronize your local repository copy to the remote master repository:
git pull
When local content is synchronized with master changes, tested, and committed locally, then push the content commits to the remote master:
git push
Note
If git requires a user password in the git push command, then an ssh key is missing at GitHub. Follow GitHub directions to add the missing key.
The original goal of this guide may seem forgotten, in that a free hosted website has not yet materialized. (You are viewing just such a site, of course, but that doesn’t count.) That goal can be achieved now if all the preliminary steps are complete.
Download script github-deploy.sh to your Projects folder, or inside of your project.
Then deploy the site at GitHub with the command:
bash gitdeploy.sh {project_foldername}
Note
If the script is executed from within your project, omit the {project_foldername} from the command.
In the web browser, substitute your GitHub username and repository name into the following URL to view the site:
http://_username_.github.com/_repository_
When viewing a site page in the browser, click the Show Source link in the side menu to display the original text source of the page.
Firefox introduced tabs in the web browser, making life better for web developers. The following five tabs are useful all the time:
`Sphinx documentation <http://sphinx.pocoo.org/contents.html>`_
`Online rst Editor <http://rst.ninjs.org/>`_
`Built HTML <file://~/Projects/doc-firsttask/_build/html/index.html>`_
`Deployed project \<http://_yourname_.github.com/_yourproject_/\>`_
`Your GitHub page \<https://github.com/_yourname_\>`_