Jeoren's syntax: {{#github:readme.md|hackersanddesigners/hdsa2019doc}}

Karl's syntax: <tool repo="REPONAME" file="FILENAME"></tool>

/ hackersanddesigners/had-py / readme.md

<div class="position-relative js-header-wrapper ">
  <a href="#start-of-content" data-skip-target-assigned="false" class="px-2 py-4 color-bg-accent-emphasis color-fg-on-emphasis show-on-focus js-skip-to-content">Skip to content</a>

  <span data-view-component="true" class="progress-pjax-loader Progress position-fixed width-full">
<span style="width: 0%;" data-view-component="true" class="Progress-item progress-pjax-loader-bar left-0 top-0 color-bg-accent-emphasis"></span>

Product
```
             Explore
```
Solutions For
- Enterprise
- Teams
- Startups
- Education
```
             By Solution
```
```
             Resources
```
Open Source
- GitHub Sponsors Fund open source developers
- The ReadME Project GitHub community articles
```
             Repositories
```
Pricing

       Search or jump to...

Search code, repositories, users, issues, pull requests...

       Search

           
             Search syntax tips

Provide feedback

We read every piece of feedback, and take your input very seriously.

         Include my email address so I can be contacted

                   Cancel

             Submit feedback

Saved searches

Use saved searches to filter your results more quickly

           Name

           Query

To see all available qualifiers, see our documentation.

                   Cancel

             Create saved search

           
             Sign in

           
             Sign up

  <div hidden="hidden" data-view-component="true" class="js-stale-session-flash stale-session-flash flash flash-warn flash-full mb-3">

    <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-alert">
<path d="M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path>

You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session.

<button id="icon-button-6ffe9bc9-faa1-4bde-a9e1-5ee1873154ff" aria-labelledby="tooltip-e6e2fa21-c7dd-4e62-a657-d311c0488b06" type="button" data-view-component="true" class="Button Button--iconOnly Button--invisible Button--medium flash-close js-flash-close">  <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-x Button-visual">
<path d="M3.72 3.72a.75.75 0 0 1 1.06 0L8 6.94l3.22-3.22a.749.749 0 0 1 1.275.326.749.749 0 0 1-.215.734L9.06 8l3.22 3.22a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L8 9.06l-3.22 3.22a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042L6.94 8 3.72 4.78a.75.75 0 0 1 0-1.06Z"></path>

Dismiss alert

<div id="js-flash-container" class="flash-container" data-turbo-replace>

     {{ message }}

<include-fragment class="js-notification-shelf-include-fragment" data-base-src="https://github.com/notifications/beta/shelf"></include-fragment>

   
     
       hackersanddesigners

   /
   
     had-py

   Public

Additional navigation options

Files

master

Breadcrumbs

had-py

/

readme.md

Blame Blame

Latest commit

History

History191 lines (119 loc) · 7.42 KB master

Breadcrumbs

had-py

/

readme.md

Top

File metadata and controls

Preview
Code
Blame

191 lines (119 loc) · 7.42 KBRaw

hackersanddesigners.nl

Website for H&D, Amsterdam.

Side A

The wiki and the backend are running on MediaWiki, acting as open-door cms, workshop space, archive for projects and knowledge.

A wiki comes with no predetermined hierarchy, which lets you create your own logic for a navigation. On the the H&D wiki we work with Forms and Templates for a better editing experience; Semantic MediaWiki for organising all bits of data and metadata on each page and Concepts to create sections and the navigation for the frontend website.

Side B

The front-end is built in Python 3.6 with:

Werkzeug to wrap the website inside an app and put it on the internet through the WSGI interface
Requests to fetch all json from the MediaWiki backend
Beautiful Soup to parse and clean up wiki’s extra markup, and to add atomic, functional css classes to html tags
Jinja to build the templates (works hand in hand w/ Werkzeug)

To run the frontend website

Requirements

terminal basics (introduction)
Python (introduction)
pip Python package manager (instructions)
venv to setup a Python environment (check this for instructions)
git!

Then

open terminal
clone the repository: git clone git@github.com:hackersanddesigners/had-py.git
setup a new Python 3.6 environment inside the repo folder: python3.6 -m venv env. To activate it, type: source env/bin/activate
type: python had.py
you will be asked to install a bunch of dependencies using Python’s pip package manager. Do pip install name-of-package and keep running python had.py until everything is installed
type: python had.py again, the Python app should start and print something like http://127.0.0.1:5000, copy that in your browser to see the H&D’s frontend website ☺︎

Some thoughts on the process

Improving and organising the MediaWiki demanded a good reading of the extensive (at times confusing) documentation, installing some plugins (in particular PageForms on top of Semantic MediaWiki) and manage the data through the MediaWiki interface. The most challenging part was to understand how Mediawiki actually treated data, and to decide how much complexity adding to the existing wiki. Overall, the aim was to be able to create new articles and to edit them in a pleasant manner but not limited the editing activities too much.

The wiki is fully able to parse different syntaxes whenever you need to embed an image, a video, an audio clip, an etherpad, etc, and it supports your writing and mark-up. One instance is the token autocompletion: for example some fields suggest you already used words (tokens) while you are typing.

Check Page Forms:Input types for an overview of what’s available.

Currently, the Event page receives data with this template

{{{for template|Event}}}

{| class="formtable"

! Name

| {{{field|Name}}}

|-

! Location

| {{{field|Location|input type=combobox}}}

|-

! Date

| {{{field|Date}}}

|-

! Time

| {{{field|Time}}}

|-

! PeopleOrganisations

| {{{field|PeopleOrganisations}}}

|-

! Type

| {{{field|Type|input type=combobox}}}

|-

! Web

| {{{field|Web|input type=checkbox}}}

|-

! Print

| {{{field|Print|input type=checkbox}}}

|}

{{{end template}}}

'''Text'''

{{{standard input|free text|rows=15|editor=wikieditor}}}

The combobox input type (see) looks up what has been already saved in that particular field from all the previous pages, and suggests possible completion.

± ± ±

Working with the frontend instead, requires to have / get some knowledge of:

restful APIs (ref)
how to handle page request, setup page routing, serve the app to the web, etc. — in this case with Python
how to use a templating library

As we decided not to use a framework, the second point in particular gives you the chance to manually fiddle with stuff than if you mostly use a (php-based) cms, usually you can avoid or don’t have to touch at all.

Working with a restful API introduces you to the powerful world of json (intro), a very flexible data format able to convert anything into anything else—and back.

When working with Python, there are two very useful commands that let you inspect a json dataset:

type(data), eg print(type(data)) — to check if the current object is a dict, or a lists, a string and so forth
data.keys(), eg print(data.keys()) — to check the object’s keys (which is how json structures data)

Alternatively, you can access to a pretty-printed version of the json request you made to MediaWiki, by visiting that url, eg

https://en.wikipedia.org/w/api.php?action=query&titles=Main%20Page&prop=revisions&rvprop=content&format=json

and adding fm after format=json, like format=jsonfm (see docs) to have an indented, more readable version

https://en.wikipedia.org/w/api.php?action=query&titles=Main%20Page&prop=revisions&rvprop=content&format=jsonfm

This double approach lets you inspect better what’s going on in case you are unsure which data you are working with.

± ± ±

Once you get acquainted with MediaWiki’s design language (Forms, Templates, etc), json data structures and some basic Python, you can play around with the website.

± ± ±

custom mediawiki styles

/mediawiki/resources/src/mediawiki.action/mediawiki.action.history.styles.css

this add more padding and take out list styles to the revision list

#pagehistory {
    margin-left: 0;
    padding-top: 0.25rem;
}
#pagehistory li {
    list-style: none;
    padding: 0.5rem;
    margin-bottom: 0.25rem;
}
#pagehistory li:hover {
    background-color: #f8f9fa;
    border: 1px dashed #a2a9b1;
}

/mediawiki/resources/src/mediawiki.action/mediawiki.action.history.css

this set the ‘compare selected revisions’ to the bottom-right, always at reach and more prominent (before there were two buttons at the top and bottom of the revision list, very much buried amongst the rest of the text)

.historysubmit {
    position: fixed;
    bottom: 0.5rem;
    right: 1rem;
    padding: 0.5rem;
    font-size: 100%;
}

.historysubmit:hover, .historysubmit:active {
    background-color: yellow;
    cursor: pointer;
}

      <footer class="footer pt-8 pb-6 f6 color-fg-muted p-responsive" role="contentinfo" >

Footer

     
       © 2024 GitHub, Inc.

Footer navigation

Terms
Privacy
Security
Status
Docs
Contact
Manage cookies
Do not share my personal information

<ghcc-consent id="ghcc" class="position-fixed bottom-0 left-0" style="z-index: 999999" data-initial-cookie-consent-allowed="" data-cookie-consent-required="true"></ghcc-consent>

   You can’t perform that action at this time.

<template id="site-details-dialog">

<div class="Popover js-hovercard-content position-absolute" style="display: none; outline: none;" tabindex="0">

<template id="snippet-clipboard-copy-button">

</div>

<div id="js-global-screen-reader-notice" class="sr-only" aria-live="polite" aria-atomic="true" ></div>
<div id="js-global-screen-reader-notice-assertive" class="sr-only" aria-live="assertive" aria-atomic="true"></div>

↗ view more tools ↗↗ view in GitHub ↗

To-Do for Article Pages

CSS
- define a max height → expandable to full height
- cute styling ◕3◕
HTML
- external link to github

To-Do for Tools Page

CSS
- max height + width
HTML
- if #github embed in article then create same embed in tools
- external link to github
- internal link to article (only in tools page)

ToolExample

Navigation Menu

Search code, repositories, users, issues, pull requests...

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Files

Breadcrumbs

readme.md

Latest commit

History

Breadcrumbs

readme.md

File metadata and controls

hackersanddesigners.nl

Side A

Side B

To run the frontend website

Some thoughts on the process

custom mediawiki styles

Footer

Footer navigation