Skip to content

photoprism/photoprism-docs

Repository files navigation

PhotoPrism: Official Documentation (English)

GitHub contributors Documentation Community Chat GitHub Discussions Bluesky Social Mastodon

These source files are written in human-friendly Markdown. They are meant to be parsed with MkDocs Material to generate the final HTML pages published at docs.photoprism.app.

Although arguably less convenient to work with than a Wiki, this enables us to easily merge pull requests and constantly improve our documentation in a transparent way. Direct access to the source files in a revision control system is a big plus to ensure the quality of our documentation.

Editing Content

At the top of each generated page is an edit this page link to the corresponding page on GitHub, where you can make changes (and submit pull requests with a few clicks) without needing to know Git or run anything on your system.

To make more extensive changes, fork this repository, modify the corresponding .md source files (or create new ones), commit the changes, push them back to your fork, and then submit a pull request to our master branch.

Project Layout

mkdocs.yml    # The configuration file.
docs/
    index.md  # The documentation homepage.
    ...       # Other markdown pages, images and other files.

Build Setup

Create .env File

If you have a personal access token for the MkDocs Material Insider edition, add you GitHub access token to an .env file in the main project directory:

GH_TOKEN=[YOUR TOKEN]

New GitHub access tokens can be generated on https://github.com/settings/tokens.

Installing MkDocs

When using a Debian, Ubuntu, or Mint Linux, run this command the first time you work with this repository on your computer so that the dependencies are installed:

make deps

Otherwise, install Python 3 and Pip manually and run the following command:

make install

Fixing Permissions

In case files in the project directory have bad permissions and mkdocs cannot read or write them:

make fix

Using MkDocs

First make sure you have Docker and common development tools like make installed on your computer.

Then use this command in the main project directory to download and run the latest version of mkdocs-material:

make watch

Now open http://localhost:8000/ in a browser to view the rendered documentation.

The content will be updated automatically when changes are detected.

Deployment

When you merge the main/master branch to deploy, the live documentation is automatically created, uploaded and will be visible shortly.

Linux/Unix users can run make merge in a terminal. Otherwise, please use the tools provided by your development environment or editor.

Contributor License Agreement (CLA)

After you submit your first pull request, you will be asked to accept our Contributor License Agreement (CLA). Visit photoprism.app/cla to learn more.

Other Documentation

Related Repositories


PhotoPrism® is a registered trademark. By using the software and services we provide, you agree to our Terms of Service, Privacy Policy, and Code of Conduct. Docs are available under the CC BY-NC-SA 4.0 License; additional terms may apply.