Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/davorg/perlwebadvice

A website containing advice for people writing web applications in Perl
https://github.com/davorg/perlwebadvice

perl web-development web-siite

Last synced: about 2 months ago
JSON representation

A website containing advice for people writing web applications in Perl

Awesome Lists containing this project

README 

        
# Perl Web Advice

A website containing advice for people writing web applications in Perl.



See [web.perlhacks.com](http://web.perlhacks.com/).



## Development environment



This web site is developed using a static sitebuilder called

[`aphra`](https://metacpan.org/dist/App-Aphra/view/bin/aphra). In order

to contribute to the site, you'll need to have `aphra` installed.



### Install dependencies



There are two important dependencies for installing `aphra` - `pandoc`

and `http_this`.



* `pandoc` is a tool for converting between various document formats. We use it for converting between Markdown and HTML. If you're working on Linux, there is almost certainly a pre-build package that you can install with a command like `dnf install pandoc` or `apt install pandoc`. On other operating systems, you should see the [`pandoc` web site`](https://pandoc.org/)

* `http_this` is a mini web server that you can use to view changes to the web site before pushing them to GitHub and deploying them to the live version web site. It is a CPAN module so you can install it using you favourite CPAN installation tool - for example, `cpanm App::HTTPThis`.



### Install `aphra`



`aphra` is also a CPAN module. So you can install it using a command like `cpanm App::Aphra`.



## Working on the site



The usual way to work on the code is to create a fork and work on that. You can then

send your changes back to us by creating a pull request.



### Fork and clone the source code



The main copy of the source code is at https://github.com/davorg/perlwebadvice.

Near the top right of that web page is a button labelled "Fork". If you press

that button, GitHub will create your own copy of the source code under your

GitHub account. You can make a local copy of your repo by clicking the big

green "Clone" button and copying the URL of your repo. You then open a

command-line terminal and type:



* `git clone [YOUR URL HERE]`



This will create a new directory called `perlwebadvice` containing a copy

of the source code.



### Understanding the source code



There are three important directories in the source code tree.



* `in` contains the actual pages that make up the web site. Each file under this directory will be copied to the live web site. If the filename ends with `.tt` it will be processed with the [Template Toolkit](https://metacpan.org/pod/Template::Toolkit) before being copied to the output directory (which is called `docs`). Any files that don't end with `.tt` are just copied over.

* `fragments` contains small sections of web pages that are inserted into the main web pages in `in`.

* `layouts` contains layout templates that are used to control the look and feel of the web pages.



### Testing your changes



Once you've made some changes, you'll (hopefully) want to test your changes

before sending them back to us. This is a two-stage process:



1. Run `aphra build`. 

This builds the site and puts a copy of the new version into the `docs` directory.

2. Run `aphra server`. 

This runs a local web server allowing you to visit a local copy of the web site at http://localhost:7007/.



### Submitting your changes



Once you're happy that your changes do what you want (and don't break anything)

you can submit them back to the main repo for incorporation into the live site.



To do this, you need to run `git add` to add any files you've added or changed

and then `git commit` to commit your changes (this will give you an opportunity

to provide a description of the changes you've made - please make that

description useful). You can then run `git push` to send the changes back to

your copy of the code on GitHub.



You can then go to the web page at:



* https://github.com/davorg/perlwebadvice/compare



to create a pull request. Leave the "base repository" dropdown as it is and

select your repo from the "head repository" link. The page will then show

your changes and (when you're happy you're submitting what you want to

submit) you can submit the pull request. Some time later, we'll look at your

pull request and either accept it or reply with suggestions for improvements.