Browse Source

Update README.md

SoniEx2 2 months ago
parent
commit
3483dbe9b5
1 changed files with 33 additions and 28 deletions
  1. 33
    28
      README.md

+ 33
- 28
README.md View File

@@ -7,32 +7,31 @@ More importantly, it's a tool to help fight against BDFLs and other forms of cen
7 7
 Basic Usage
8 8
 -----------
9 9
 
10
-Note: GAnarchy does not come with a main page. You need to provide one yourself. This should be in your website's `/` path (usually `index.html`).
11
-The protocol handler uses the path `/?url=%s`. Additionally, your main page needs to include the `index.js` provided by GAnarchy
12
-for the protocol handler to properly work.
13
-
14 10
 First, initialize the database with `ganarchy.py initdb`. The database is stored in the XDG data home, as per XDG spec.
15 11
 
16
-Then, set the project commit with `ganarchy.py set-commit COMMIT`, where `COMMIT` is the full commit hash.
17
-The commit *must* start with `[Project]` followed by the project name, and may have an optional description.
18
-(Note: This requirement isn't properly checked, but will be in the future. This is important for a future federation
19
-protocol that allows for automatically discovering forks based on the project commit.)
20
-
21
-Once everything is initialized, add some repos with `ganarchy.py repo add URL`, and enable or disable them with `ganarchy.py repo enable URL` or
22
-`ganarchy.py repo disable URL`. They currently come enabled by default. You are now ready to go.
23
-
24
-Finally, add `ganarchy.py cron-target > path/to/page.html` to your cron. Optionally `scp page.html scp://server@example.org/page.html`.
12
+Then create or edit the file `$XDG_CONFIG_HOME/ganarchy/config.toml`. It should contain the following items:
25 13
 
26
-Example shell session:
27
-
28
-```text
29
-$ ganarchy.py initdb
30
-$ ganarchy.py set-commit 385e734a52e13949a7a5c71827f6de920dbfea43
31
-$ ganarchy.py set-project-name GAnarchy
32
-$ ganarchy.py repo add https://cybre.tech/SoniEx2/ganarchy
33
-$ ganarchy.py cron-target > index.html
34
-$ scp index.html scp://example.org/var/www/html/index.html
35 14
 ```
15
+# Example GAnarchy config
16
+
17
+# The base_url is the web address of the GAnarchy instance
18
+# Restrictions: MUST be present. SHOULD be https.
19
+base_url = "https://ganarchy.autistic.space/"
20
+
21
+# The title is shown on the homepage. If not present, defaults to "GAnarchy on [base_url's hostname]"
22
+title = "GAnarchy on autistic.space"
23
+
24
+# The projects table is made up of "project commit" hashes (see below for project commit)
25
+[projects.385e734a52e13949a7a5c71827f6de920dbfea43]
26
+# Each project is made up of repos and branches
27
+# HEAD is special and refers to the default branch
28
+# Restrictions: active MUST be present, file URLs are disallowed
29
+"https://cybre.tech/SoniEx2/ganarchy".HEAD = { active=true }
30
+# repos/branches with active=false will not be shown or updated
31
+"https://cybre.tech/SoniEx2/ganarchy".broken = { active=false }
32
+```
33
+
34
+A project commit is a commit that *must* start with `[Project]` followed by the project name, and may have an optional description.
36 35
 
37 36
 Example project commit:
38 37
 
@@ -43,13 +42,19 @@ A Project Page Generator written in Python, focused on giving forks of a
43 42
 project the same visibility as the original repo.
44 43
 ```
45 44
 
45
+To generate the output pages:
46
+
47
+```
48
+ganarchy.py cron-target index > index.html
49
+ganarchy.py cron-target config > config.toml # if federation is desired
50
+ganarchy.py cron-target $PROJECT_COMMIT > project/$PROJECT_COMMIT/index.html # for each project
51
+```
52
+
53
+It's recommended to use a wrapper script to generate the project pages. `ganarchy.py cron-target project-list` may be of use.
54
+
46 55
 Advanced Usage
47 56
 --------------
48 57
 
49
-It's also possible to use the same GAnarchy DB with multiple projects. This is currently done by passing `--project COMMIT` to the `repo` commands,
50
-and using `cron-target COMMIT`.
51
-
52
-Note that the same repo may be part of multiple projects, so it is necessary to specify `--project COMMIT` also when enabling/disabling it.
58
+In addition to the basic configuration above, you can also place your own templates in `$XDG_CONFIG_HOME/ganarchy/templates`.
53 59
 
54
-Additionally, it's possible to set a non-default branch by passing `--branch BRANCHNAME` to the `repo` commands. Given that multiple branches of
55
-the same repo may be part of the same project, it is also necessary to use `--branch BRANCHNAME` when enabling/disabling them.
60
+The current templates are: `index.html`, `index.toml`, `project.html`.

Loading…
Cancel
Save