kompot
/
publiccode.si
5
3
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update README to cover the build and path changes

lektura
max.mehl 2017-06-19 23:51:56 +02:00
parent 6bf3b4c920
commit 4029be1dff
1 changed files with 23 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
README.md
View File

@ -2,13 +2,13 @@
This website is the core of the "Public Money, Public Code" campaign. It is based on [Hugo](https://gohugo.io/), a modern static website generator.
The page is visible at [publiccode.eu](https://publiccode.eu). Please do not spread this URL.
The page is visible at [publiccode.eu](https://publiccode.eu). Please do not spread this URL. The website requires authentication to be visited. Username is `pmpc`, password is `publicmoneypubliccode`. Please do not spread this information to outside people not involved in the website development.
## Contributing to the website
### Prerequisites
In order to modify the website, you need `hugo` and `git` installed on your computer. If Hugo isn't available in your package manager, obtain it from its [official website](https://gohugo.io). The latest Hugo version is 0.19, older versions haven't been tested. Please make sure that you use an as recent version as possible to avoid errors.
In order to modify the website, you need `hugo` and `git` installed on your computer. If Hugo isn't available in your package manager, obtain it from its [official website](https://gohugo.io). We tested the website build with Hugo from version 0.19 upwards. Please make sure that you use an as recent version as possible to avoid errors.
### Configuring Git
@ -16,24 +16,11 @@ First of all, you'll need an account on git.fsfe.org. With an FSFE account (FSFE
As part of the campaign team you can get full write access to this repository. Please contact one of [pmpc](https://git.fsfe.org/pmpc)'s admins to give your account the necessary privileges.
The most comfortable way for you to use Git is to use SSH keys for authentication. They won't require you to type in your username and password each time. Please read a [manual from Github](https://help.github.com/articles/connecting-to-github-with-ssh/) on the usage of SSH keys with their service. Although Github looks a bit different, it may help you understanding the logic. Please replace `github.com` with `git.fsfe.org`. However, a short step-by-step list:
1. Check whether you already have an SSH key (`ls -al ~/.ssh`)
2. If not generate a new SSH key (`ssh-keygen -t rsa -b 4096 -C "your_email@example.com"`). Omit typing in a password if you are sure that you can protect your SSH private key. If you set a password, consider using `ssh-agent` to avoid having to type in the SSH key's password each time you use it.
3. Add the public SSH key to your account at git.fsfe.org. Copy the content of `.~/ssh/id_rsa.pub` in `Your Settings > SSH Keys > Add Key`.
4. Try to log in (`ssh git@git.fsfe.org`). If you read "Hi there, You've successfully authenticated, but Gitea does not provide shell access.", it's working!
Then you have to set your git identity and a required default setting for git pushes:
```sh
git config --global user.name "John Doe"
git config --global user.email johndoe@example.com
git config --global push.default simple
```
In the FSFE's wiki, you'll find [information about our Git server](https://wiki.fsfe.org/TechDocs/Git) installation, and some guides for basic procedures.
### Cloning the website
Now navigate to a directory on your computer where you want the PMPC website to be stored. In this example, it's `FSFE/PMPC/website` in your user's directory.
Although the mentioned Git guides will enable you to understand how to download the website's repository, here's a short howto: Navigate to a directory on your computer where you want the PMPC website to be stored. In this example, it's `FSFE/PMPC/website` in your user's directory.
```sh
mkdir -p ~/FSFE/PMPC/ # Create the directory if it doesn't exist yet
@ -41,34 +28,37 @@ cd ~/FSFE/PMPC/ # go to the newly created PMPC d
git clone git@git.fsfe.org:pmpc/website.git # clone the website to the folder website
```
In the newly created folder `pmpc-website` you'll find all source files the website consists of now.
In the newly created folder `pmpc-website` you'll find all source files the website consists of now. The hugo files are located under site/, whereas in the root directory you'll only find files informational files and those relevant for our build process (Drone, Ansible, Docker, Apache).
### Your first modification
Now we will modify the website a bit, review the changes and push them to the repository to make them available to other users and the live website.
For more experienced Git users we recommend the Fork & Pull Request workflow, which you'll also find in the [wiki's Git Guides section](https://wiki.fsfe.org/TechDocs/Git#Guides_on_specific_actions) (not available yet). However, beginners can also directly commit to the repository which saves them some steps.
As an example, we will modify the website a bit, review the changes and push them to the repository to make them available to other users and the live website.
1. Navigate to the website's root directory (in the last example `~/FSFE/PMPC/website/`) and open a terminal window there. Type in `git pull`. This will get the latest changes from the server
2. After you received the latest version, you can edit the website. For testing purposes, open the file `CONTRIBUTORS.md`, scroll to the very end, and add your name there. No worries, this won't have any visible effect on the website.
3. Now check whether the website looks fine. Execute `hugo server` on your terminal. You will see a link containing `localhost:1313`. Open it and you see a preview of what the website looks like. This will help you to understand whether your changes actually have the effect you wanted.
4. If you're happy with it, you can execute `hugo`. This will build the website in its final form to the subfolder `public`. Make sure that the output of that command doesn't contain any errors or warnings. Note that your local built won't be sent to the server because it builds the website itself.
5. Check with `git status` what files have been changed on your side. In this example, you should see the file `CONTRIBUTORS.md` marked red. This means that the file has been changed but you didn't mark it as to be pushed to the server yet. If there're more files listed, make sure that you actually intended to modify these files!
6. Add the changed file to the commit queue with `git add CONTRIBUTORS.md`. In case you have changed more files, you can also type `git add .` to add all files at once. With `git status` you should see all files marked green now, which means that they're ready to be committed.
7. Commit the files with `git commit -m "added myself to the contributors list"`. In the comment after `-m` you should always write something meaningful that helps people to understand what you actually did.
8. Unlike with SVN, you're not finished yet. You will have to execute `git push` to actually upload the modifications to the server.
3. In the terminal, execute `cd site/` to navigate in the right directory for hugo's website build.
4. Now check whether the website looks fine. Execute `hugo server` on your terminal. You will see a link containing `localhost:1313`. Open it and you see a preview of what the website looks like. This will help you to understand whether your changes actually have the effect you wanted.
5. If you're happy with it, you can execute `hugo`. This will build the website in its final form to the subfolder `public`. Make sure that the output of that command doesn't contain any errors or warnings. Note that your local built won't be sent to the server because it builds the website itself.
6. Check with `git status` what files have been changed on your side. In this example, you should see the file `../CONTRIBUTORS.md` marked red. This means that the file has been changed but you didn't mark it as to be pushed to the server yet. If there're more files listed, make sure that you actually intended to modify these files!
7. Add the changed file to the commit queue with `git add ../CONTRIBUTORS.md`. In case you have changed more files, you can also type `git add .` in the repositories root level to add all files at once. With `git status` you should see all files marked green now, which means that they're ready to be committed.
8. Commit the files with `git commit -m "added myself to the contributors list"`. In the comment after `-m` you should always write something meaningful that helps people to understand what you actually did.
9. Unlike with SVN, you're not finished yet. You will have to execute `git push` to actually upload the modifications to the server.
## Important file paths
The website structure is very easy. The most important files and directories are:
- `config.toml`: Headlines, site title, many texts.
- `data/resources/`: Content of the 3-column "resource" boxes which you can hover over and click to see the text.
- `data/share/`: Services where people can share to. Is being used in the "Spread" section and the left-side sharing icons
- `static/`: CSS, images, and Javascript files for the design.
- `static/img/share/`: Image files for share buttons.
- `static/css/custom.css`: File where all custom CSS code should be written to.
- `layouts/`: HTML structure (scaffold) for the website. Useful if you want to add another section or modify anchor links or CSS classes.
- `public/`: Built files which are used to display the website. Generated by running `hugo`.
- `site/config.toml`: Headlines, site title, many texts.
- `site/data/resources/`: Content of the 3-column "resource" boxes which you can hover over and click to see the text.
- `site/data/share/`: Services where people can share to. Is being used in the "Spread" section and the left-side sharing icons
- `site/static/`: CSS, images, and Javascript files for the design.
- `site/static/img/share/`: Image files for share buttons.
- `site/static/css/custom.css`: File where all custom CSS code should be written to.
- `site/layouts/`: HTML structure (scaffold) for the website. Useful if you want to add another section or modify anchor links or CSS classes.
- `site/public/`: Built files which are used to display the website. Generated by running `hugo`.
## Technical information about building