Sunnyside-Times Operating Commands
Commands to maintain the system are implemented by plugins. There are many plugins built into Nikola and they can be referenced here. This page is more concerned about the commands used in the day-to-day operation and maintenance of the site.
Commands are run on a command line in the directory containing the site. The project directory is sst_static/, and the site within that directory is sst/. Commands are of the form nikola command args. Most commands needed do not normally require any args.
This command supports maintenance of the site, particularly by the content managers. When run, it adds two menu items to the Sys_Admin menu. PHOTO USAGE DATA provides some summary statistics such as the number of pages and galleries, the number of unused pages and galleries, etc. It also provides a list of urls for all unused pages and galleries. PAGES TO PHOTOS is a searchable listing that maps each page to the photos and galleries that are referenced by it.
This command converts a docx file into a .md file. There is a directory (docx_pages) under support. Docx files are placed in that directory along with a corresponding meta file. When this command is run, it creates a .md file also in that directory. A copy of that created file is placed in the appropriate directory in pages (the .md file is no longer needed). In general, once a file has been processed, it may be removed as the converted file in the pages directory will serve as the new master file.
The .meta file has a path attribute that gives the directory to which the .md file is to be copied (e.g., ".. path: /pages/cool-stories-index/resident-told-stories/" ).
We assume that all photos and their appropriate locations are communicated separately.
The pages in migration command is intended to support files that may be created or modified outside the pages directory. It is also useful for creating new instances of existing pages before they are updated to the production site.
Running pages_in_migration will replace any instances of files of the same name that already exist in the pages directory. Pages to be migrated are maintained in the migrating_pages directory. Pages in the support/admin directory are also processed to update sys_admin documentation.
The multi_pages command is used to build Page One, Page Two or other similarly complex pages. Each such page is described by a folder named the same as the target page being created. The structure of the files in that folder is described under the Multi-Story Pages menu item.
Entries in the users.csv file are the user name possibly followed by a password. If no password is provided, the default Sunny password is used.
Individual users may be added or removed by adding parameters -f (add or remove) with a username (--user or -u) in double quotation marks (because of spaces) and optionally a password (password or -p). If the password is omitted, the system default is used.
The new_residents command creates a page which is generally added to Page One identifying the new residents. It uses a definition file new_residents.yaml that is maintained in the sst_static/support/work_files/ directory. The result are two files: new-residents.html and new-residents.meta in the pages directory of the site.
It can be updated manually or, preferably, automatically updated (software yet to be written) from an available primary source.
The convert_shortcodes command processes all shortcodes contained in the source files into appropriate html or other content. The shortcodes are described here
The build command is the Nikola provided command to build the site. nikola build -a can be used to force nikola to rebuild the site in its entirety. Otherwise, nikola attempts to build only those pages that have been modified, making it very fast.
The normal sequence for creating/updating a site, after making any desired changes is:
- nikola new_residents
- nikola pages_in_migration
- nikola convert_shortcodes
- nikola multi_pages
- nikola build
At that point the new site is constructed, deployed, and live (assuming there is a running web server).