digiKam

Professional Photo Management with the Power of Open Source

Meta - Writing


Writing content for the website is a bit different compared to using a CMS (like the previously used Drupal).

The biggest change is that the website data is now being tracked in a version control system, Git.

Contributors that want to write content for the site only need to write their content as a plain text markdown file.

This file and any associated assets required (such as images) can then be delivered to responsible team members to be checked and then published.

Writing Quick Start

  1. Download or install Hugo (at least v0.19) (and put it in your path).
  2. Clone the digikam-org website from the git repository.
  3. Open a terminal and navigate to /path/to/digikam-org/
  4. Use the hugo new command to create new content. For example, the command hugo new news/2017-01-01-my-new-post.md creates a new News article with the necessary metadata.
  5. Open the new file in your text editor of choice.
  6. Fill in the YAML metadata at the top of the file.
  7. Write the page content in markdown.
  8. Visually inspect your new post using the command hugo serve. Open a web browser and go to http://localhost:1313

Markdown

Markdown is a method for marking up plain text files with basic information and formatting using a very simple syntax.

File Naming Convention

News items have been using a naming convention:

YYYY-MM-DD_The_News_Item_Descriptive_Name.md

You can use the hugo new command to create new content using a template. The template will automatically be chosen according to what path your choose to create your new content. For example, hugo new news/2000-01-01-the-party-is-over.md will use the news template located in digikam-org/archetypes/news.md.

Contributors can help ease management of data by following a similar convention. :)

If they do not, the committer should probably remember to rename contributed files if possible (it won’t break the build or anything, just makes it easier to manage files).

Image Storage Location

For News articles: digikam-org/static/img/news/<news article name>/

For example, digikam-org/static/img/news/2017-01-01_happy_new_year/ball-drop.jpg would be the file system path to your image. You could then reference it from your news article ![The ball dropping](/img/news/2017-01-01_happy_new_year/ball-drop.jpg). Note that the path starts with / making it an absolute location from the web server root.

For other pages: digikam-org/static/img/<page category>/

For example, digikam-org/static/about/digikam-team-photo.jpg would be the file system path to your image. You could then reference it from your news article ![The ball dropping](/img/about/digikam-team-photo.jpg). Note that the path starts with / making it an absolute location from the web server root.

Viewing the Site Locally

Before submitting a patch or pushing to the git repo, you should preview the site locally and ensure that everything appears as you would like it to.

You can view the site locally by completing the following steps:

  1. Download or install Hugo (at least v0.19) (and put it in your path).
  2. Clone the digikam-org website from the git repository.
  3. Open a terminal and navigate to /path/to/digikam-org/
  4. Run the command hugo serve.
  5. Open a web browser and go to http://localhost:1313

You see the digiKam website.

Publishing Changes

Git Access

If your account is a developer account (has push access to the repository), you can publish news items by committing and pushing to the repository. This should normally be done against the dev branch first to check that everything works and looks good.

If so, it can then be merged into the master branch.

Out-of-band Submissions

If you do not have developer access to the website repository or did not want to clone the repo, you can submit your article in several ways:

  • Email the markdown content and images to someone with a developer account
  • Post the content to the mailing list
  • Use a gist or pastebin service to post the text, then send the link to someone with access
  • Open a bugzilla bug and include the text of the post