{"id":27633060,"url":"https://github.com/libsdl-org/ghwikipp","last_synced_at":"2025-04-23T18:04:04.107Z","repository":{"id":44978395,"uuid":"340099956","full_name":"libsdl-org/ghwikipp","owner":"libsdl-org","description":"A slight improvement on GitHub's current wiki support.","archived":false,"fork":false,"pushed_at":"2025-01-16T16:56:46.000Z","size":234,"stargazers_count":32,"open_issues_count":2,"forks_count":13,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-01-16T18:14:20.539Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"zlib","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/libsdl-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-18T15:53:47.000Z","updated_at":"2025-01-16T16:56:48.000Z","dependencies_parsed_at":"2024-09-17T02:02:47.918Z","dependency_job_id":"f8fe448e-8f16-4e1c-8de8-86fb4cf50090","html_url":"https://github.com/libsdl-org/ghwikipp","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libsdl-org%2Fghwikipp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libsdl-org%2Fghwikipp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libsdl-org%2Fghwikipp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libsdl-org%2Fghwikipp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/libsdl-org","download_url":"https://codeload.github.com/libsdl-org/ghwikipp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250487530,"owners_count":21438612,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-23T18:01:59.443Z","updated_at":"2025-04-23T18:04:04.100Z","avatar_url":"https://github.com/libsdl-org.png","language":"PHP","funding_links":[],"categories":["PHP"],"sub_categories":[],"readme":"\n# ghwikipp\n\n(That's \"GitHub Wiki++\" because programmers shouldn't name things.)\n\nThis is a little glue to make GitHub wikis nicer (I hope).\n\nThe idea is that:\n- We want to use a git repo for our wiki revision history.\n- We mostly want to edit in a web UI, but want the power to edit\ntext files directly, run scripts over them, etc.\n- We want to allow contributions from the outside world with low\noverhead, but we also want to avoid spammers.\n\nSo this thing runs on your own server, but talks to GitHub through\nAPI calls and repo pushes.\n\nAnyone can read the wiki anonymously. Editing bounces you to GitHub\nto log in. If your GitHub account is trusted, edits to the wiki will\nbe pushed directly to main and show up immediately on the website.\nIf you aren't a trusted user, your edits become pull requests that\nwe can examine, comment on, and eventually merge.\n\nIf we like your pull requests, we can mark you trusted. If we don't\nlike _you_, we can block you and the wiki won't let you submit any\nmore edits.\n\nAll wiki pages are either Markdown or MediaWiki format. An offline\narchive of the wiki pages, as HTML, is generated once per day and\navailable from the website, and the raw markdown pages are just a\nsimple git clone.\n\nVarious pieces of UI are handed off to GitHub (See history of \nchanges to a page? You get sent to the log on GitHub. Feedback on\na page without a specific edit? They land in GitHub Issues, etc),\nto keep this small and use the existing tools for greater effect.\n\n\n# To install:\n\nThis thing has a lot of moving parts, and setting them up is daunting.\nDo your best, ask for help if you need it, correct me if I explained\nsomething incorrectly.\n\n* You'll need a server that can run PHP code (mod_php on Apache or\nwhatever) that allows you to access the filesystem and run shell\ncommands on. Git, pandoc, command line PHP, and some other minor Unix\ncommand line tools have to be installed, and accessible to the PHP\ncode, here. You will absolutely need to be able to serve webpages over\nSSL with a valid SSL certificate, as GitHub will require this to\ntalk to your server.\n\n* We set this up as a new virtual host on Apache that serves wiki\ncontent from the root directory of the host. This probably needs some\nbugs fixed to work out of a subdirectory of an existing virtual host.\nOur config looks like this... (notably: the first Alias makes one\ndirectory serve static files, and _every other url_ goes through\nthe PHP script. And, of course, `php_flag engine on` is crucial).\n\n```\nServerAdmin webmaster@libsdl.org\nDocumentRoot \"/webspace/wiki.libsdl.org\"\nServerName wiki.libsdl.org\n\nErrorLog /var/log/apache2/error_log_wiki_libsdl_org.log\nCustomLog /var/log/apache2/access_log_wiki_libsdl_org.log combined\n\nAlias /static_files \"/webspace/wiki.libsdl.org/static_files\"\nAlias / \"/webspace/wiki.libsdl.org/index.php/\"\n\n\u003cDirectory \"/webspace/wiki.libsdl.org\"\u003e\n    Options +Indexes +FollowSymLinks\n    AllowOverride Limit FileInfo Indexes\n    Require all granted\n    php_flag engine on\n\u003c/Directory\u003e\n```\n\n* Make a new user on GitHub. This is your wikibot. We called ours\n\"SDLWikiBot\". Give it a legit unused email address you can verify \nfrom (we'll call it `$WIKIBOT_EMAIL` in shell commands, later).\n\n* Set this new user up in a reasonable way. Go through all the settings.\n\n\n* Clone the ghwikipp repo to the proper directory on your webserver\n(this would be `/webspace/wiki.libsdl.org` in the config above, we'll\ncall it `$MY_VHOST_ROOT_DIR` here. Set an environment variable.)\n\n```\ngit clone git@github.com:libsdl-org/ghwikipp.git $MY_VHOST_ROOT_DIR\n```\n\n* And clone _your wiki_ under that, in a directory called `raw`:\n\n```\ngit clone git@github.com:$MY_GITHUB_USER/$MY_WIKI_REPO.git $MY_VHOST_ROOT_DIR/raw\n```\n\n* Set up a ssh key for pushing changes to the wiki (hit enter for all questions) ...\n\n```\ncd $MY_VHOST_ROOT_DIR\nssh-keygen -t ed25519 -C $WIKIBOT_EMAIL\n```\n\n* Print your new ssh public key to the terminal:\n\n```\ncat id_ed25519.pub\n```\n\n* You should see a line that starts with `ssh-ed25519` and ends with your\nwikibot email address.\n\n* Go here logged in as the wikibot: https://github.com/settings/keys\n\n* Click the \"New SSH key\" button. On the next page, give it whatever you\nwant for a title, and paste that `ssh-ed25519` line from the terminal\ninto the \"key\" textarea, and click \"Add SSH key\" ... now your wikibot can\npush changes to GitHub.\n\n* Go here logged in as the wikibot: https://github.com/settings/tokens\n\n* Click \"Generate new token\". Make the note \"Wiki API access\" or whatever,\nclick \"repo\" in the scopes section so it fills in a bunch of checkboxes\nunder it. Scroll down and click the \"generate token\" button. It will\nshow you a long string of characters. _Copy this somewhere_ as it won't\nbe shown to you again.\n\n* Log out as wikibot, you're done with this for the moment.\n\n* Go back to _your normal_ GitHub account, and visit the \"settings\" page\non the new wiki project. Click on \"Manage access\" and invite the wikibot\nto this project with write access. Then, logged in as the wikibot, accept\nthe invitation (which might require you to click a link in an email sent\nto the wikibot's address). Now the bot can push changes to this repo.\n\n* From your GitHub organization's settings page (or if you don't have an\norganization, your personal settings page), click on \"Developer settings\"\nand then \"OAuth Apps\". Click \"Register an application\". Put the name in\nas whatever (this will be shown to end users, so \"MyProject's Wiki\" is\nprobably good). \"Homepage URL\" should be your virtual host's URL.\n\"Application description\" should be something like \"This application\nverifies your GitHub username before you are allowed to make changes to\nMyProject's wiki.\" Set the \"Callback URL\" to the virtual host's URL, and\nclick \"Create application.\"\n\n* On the next page, click \"Generate client secret\" and _copy the string\nit gives you_ ... you can't get it again later. Also copy down the\n\"Client ID\" string.\n\n* On your wiki's project page, click \"settings\", then \"webhooks\", then\n\"add webhook\". For this, set the \"Payload URL\" to \"github/webhook\" on\nyour virtual host's address (so, for wiki.libsdl.org, this would be\nset to `https://wiki.libsdl.org/github/webhook`). \"Content-Type\" should\nbe set to \"application/json\" ... You can write anything in the \"Secret\"\nfield as long as it's secret. A long string of numbers and letters,\ndoesn't matter, just copy it somewhere because your server needs to know\nit too. Select \"just the push event\" for which events you want sent, and\nclick \"Add webhook\".\n\n* Back in your virtual host's directory, copy the sample config...\n\n```\ncp config.php.sample config.php\n```\n\n* ...and then edit config.php to fit your needs. All those strings you\nwere supposed to copy, above? They go in this file.\n\n* Copy your own logo and favicon.ico to the \"static_files\" directory.\n\n* Set up a cronjob to build the offline archive once a day:\n\n```\nsudo ln -s $MY_VHOST_ROOT_DIR/make_offline_archive.php /etc/cron.daily/build_offline_wiki_archive\n```\n\n* Make sure everything is fully readable/writable by the webserver user:\n\n```\nchown -R www-data:www-data $MY_VHOST_ROOT_DIR\n```\n\n(if you don't have root access, you might be able to set up a cronjob\nfor your specific user. Nothing about this _needs_ root privileges.\nRead the manual.  :) )\n\n* Okay, now we're getting somewhere! Go to your vhost in a web browser\nand see if it chokes. It will probably complain that FrontPage is\nmissing. Click \"edit\" ... you should be tossed over to github to verify\nyou're a real person. Permit authorization and you'll be back to edit\nthe wiki page. (unless you revoke this authorization in GitHub's settings\nor log out, you won't have to see GitHub again for reauthorization).\n\n* Just write \"hello world\" and save it. If you didn't set yourself up as\nan admin, you should end up with a pull request on the wiki github repo,\notherwise you'll get a commit pushed to main (master, whatever) for your\nnew change. This will fire GitHub's webhook, which will cause your server\nto recook all the existing wiki data on this first run. If you have a\nbig wiki, give it a few minutes. Otherwise, you should be good to go.\nMark a few people as admins, so they can mark people as trusted to make\ndirect pushes instead of pull requests, as appropriate.\n\n* Set up a cronjob to run build_categories.php, if you want the wikibot\nto build category pages and push them. Once an hour or once a day is probably\nfine. SDL currently has a small script that runs when the wiki's git\nrepository gets new pushes that runs build_categories.php every time, for\nfaster updates.\n\n* Install codesearch:\n\n```\nsudo apt-get install codesearch\n```\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flibsdl-org%2Fghwikipp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flibsdl-org%2Fghwikipp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flibsdl-org%2Fghwikipp/lists"}