Tag: Project Largo

How To Use GitHub Wikis For Collaborative Documentation

Posted on by Ben Keith

This week I've been updating the documentation for INN's Largo WordPress theme. The documentation previously lived on the project website but we're now adding a wiki attached to the INN/Largo repository on GitHub.

In this post I'll use the Largo wiki as an example to show you how to setup a Github wiki for your project.

Setup

GitHub wikis are themselves git repositories.1 This means you can keep track of changes to the wiki and accept issues and pull requests to a repository made to contain the wiki.

To allow contributors outside of our team to submit pull requests and issues to the wiki, it makes sense to set it up as a separate repository. When the project updates, we'll push updates from the wiki repository to the wiki on the main repository for the project.

For our purposes, the container repository for the wiki is called Largo-docs.

These are the remotes I have for Largo-docs:

$ git remote -v
origin	git@github.com:INN/Largo-docs.git (fetch)
origin	git@github.com:INN/Largo-docs.git (push)
wiki	git@github.com:INN/Largo.wiki.git (fetch)
wiki	git@github.com:INN/Largo.wiki.git (push)

The first remote there, origin, is the container repository for the wiki content (Largo-docs). The second is the wiki that's attached to the main Largo theme repo.

On GitHub, the URIs for project wikis insert .wiki between projectname and .git.

GitHub project wikis are ‘magical’ repositories that are associated with your project, but are not part of the project repository. When you push to them, the wiki is rebuilt with the new content automatically. If you use GitHub pages, it’s very similar.

Since Largo-docs is just another GitHub repository, you can provide users a link to the repository’s issues page, where they can give you suggestions and pull requests. If you want to allow people to contribute to the wiki without allowing people to directly edit the wiki, this is the way to do it.

When it comes time to publish new content to the wiki associated with the main theme repository, I make sure I'm on the master branch of the Largo-docs repository and then I push to the remote I set up for the wiki on the main Largo repository.

It's as simple as:

git checkout origin/master
git push -u wiki master

Organizing the Wiki Repository

Keeping the wiki in a separate repository also makes organization easier.

By default, GitHub wikis are flat, with no hierarchy. Inside a repository, you can create folders and place individual wiki pages in them.

screenshot

These pages are simply separate files, where the filename becomes the page name. For example, example-filename_here.md becomes “example filename_here” - use capitalization and dashes to create proper article titles.

The folder structure isn't reflected when GitHub generates the wiki, but it's great for your own organization.

If you want to structure the wiki, with some posts being parents to others, you can create a table of contents for the wiki and put it in a file named _Sidebar.md. The underscore is important.

screenshot-2

Create the hierarchy with an ordered or unordered list, and use horizontal rules as separators. Within posts, use Gollum syntax to link between pages.

Authoring and Editing

GitHub doesn't use straight Markdown for wikis, though. Wikis can use nine different markup languages for posts, with Gollum syntax used for internal links and images.

Mixing Gollum and Markdown markup leads to some interesting formatting, but nothing deal-breaking. In the container repository, GitHub will only render GitHub-Flavored Markdown (GFM). The Gollum-style inter-page links and image links will be ignored, leading to situations like this in the container repo:

This is what happens when you mix Gollum link markup and Markdown in a page: GitHub only renders the Markdown.
This is what happens when you mix Gollum link markup and Markdown in a page: GitHub only renders the Markdown.

Not pretty, but hey, it works!

If you're looking to document your project in a way that others can contribute to, but you don't necessarily want to open wiki editing to everyone, this is a great way to do it!

And of course you're welcome to contribute and help improve our documentation at https://github.com/INN/Largo-docs.

1: So are GitHub Gists, incidentally. And since May 1, 2014, you can use GFM task lists in wikis.

Project Largo Goes International

Posted on by Adam Schweigert

Recently INN member Centro de Periodismo Investigativo (CPIPR) debuted a new website, the first INN member to translate our open source Project Largo WordPress theme into Spanish.

The new Centro de Periodismo Investigativo website is the first to translate INN's Largo WordPress theme into Spanish.
The new Centro de Periodismo Investigativo website is the first to translate INN's Largo WordPress theme into Spanish.

With the launch of their new site, CPIPR joins over 20 INN members and 50 other sites around the globe who are now using INN's Project Largo, including sites in Danish, French, Spanish, Portuguese and even Korean. A complete list of the sites using Largo can be found on the Project Largo website.

While many of these sites publish in different languages, the CPIPR site marks the first time we worked with a member to translate the Largo theme itself so that all of the interface elements are now available in Spanish for any other site by simply selecting "Spanish" as their language preference when they install WordPress.

For more details on how WordPress language support works, see this article from their official documentation.

The updated translation files are available now on github and if you'd like to help us translate Largo into other languages, get in touch and we'd be happy to walk you through the process.

Largo Project Sites Tweet Like The NY Times With New WordPress Plugin

Posted on by Adam Schweigert

Last week the New York Times rolled out a new feature to make it easier for readers to share notable quotes to Twitter from their story about auditioning for Saturday Night Live. This generated a fair amount of interest in news design circles.

A new WordPress plugin makes it easy to tweet selected excepts from stories.
A new WordPress plugin makes it easy to tweet selected excepts from stories.

Joshua Benton of Nieman Lab liked what he saw and uncovered a WordPress plugin that does something very similar. After modifying it a bit for use on the Nieman Lab site, Yuri Victor of the Washington Post contributed some additional features and this afternoon I thought I would customize it just a bit further and make it available to all of INN's Largo Project sites.

A quick sidenote: If you're not familiar with Project Largo, it's INN's responsive WordPress framework we've developed to help our members quickly get up and running with top-notch websites powered by WordPress that look great on any device. It's fully open source so even if you're not a member of INN you can grab the code here or get in touch if you would like to learn more.

For the Largo sites that INN hosts, this new tweetable text feature is already active on your site. If you use Largo but host elsewhere you can grab our custom version of the plugin here.

The basic usage is as follows:

Schardt says that [tweetable]finding creative journalists with an awareness of what technologies are available to them is half the battle.[/tweetable] The advancements themselves outpace the average newsroom's awareness and ability, but funding continues to be overwhelmingly aimed at furthering these platforms — while journalists struggle to keep up.

Optionally, you can include an alt tag in the shortcode if you want the text of the tweet to be different than the exact text you're highlighting:

Schardt says that [tweetable alt="This is actually the text that will show up in the tweet."]finding creative journalists with an awareness of what technologies are available to them is half the battle.[/tweetable] The advancements themselves outpace the average newsroom's awareness and ability, but funding continues to be overwhelmingly aimed at furthering these platforms — while journalists struggle to keep up.

You can also add hashtags to the tweet:

Schardt says that [tweetable hashtag="#journalism #publicmedia"]finding creative journalists with an awareness of what technologies are available to them is half the battle.[/tweetable] The advancements themselves outpace the average newsroom's awareness and ability, but funding continues to be overwhelmingly aimed at furthering these platforms — while journalists struggle to keep up.

Or add an @username to use as the "via" source of the tweet:

Schardt says that [tweetable via="INN"]finding creative journalists with an awareness of what technologies are available to them is half the battle.[/tweetable] The advancements themselves outpace the average newsroom's awareness and ability, but funding continues to be overwhelmingly aimed at furthering these platforms — while journalists struggle to keep up.

(For sites using Largo this will automatically populate with your organization's Twitter @username if you have added it on the Appearance > Theme Options page.)

And the result looks like this .

Give it a try and let us know what you think!

New Orleans’ The Lens Latest INN Member to Launch Largo Powered Site

Posted on by Adam Schweigert

We're excited to announce the launch of the latest INN member site using our Largo platform: The Lens in New Orleans.

From their announcement:

The new site automatically adjusts to fit screens, whether you’re using an iPad, an Android tablet, an iPhone or a Samsung Galaxy S III. If you’re reading this on a computer, resize your browser window to see how it reacts.

We’ve used larger type, a clean, distraction-free layout and an added ability to highlight important facts and figures within stories.

The Lens’ Charter School Reporting Corps has become the pre-eminent source of information about the charter schools in New Orleans: For the past two years, we’ve covered nearly every meeting of the more than 40 charter boards in the city. No other news source comes close. This coverage has been integrated into the rest of the site and given more prominence on the home page. The individual school pages have been redesigned to provide essential information on each school. And readers can continue to subscribe to email alerts for one or many schools.

A new navigation enables us to highlight our ongoing stories and investigations, which means users can spend less time looking for the stories and more time reading and sharing them.

We’re not done yet. We’ve placed new priority on giving people access to primary source documents. Upcoming changes will provide users even more access to documents, including public records that are harder to get than they should be.

The home page also features Muckreads, ProPublica’s selections of the best watchdog reporting from around the country.

The new site is the product of cooperation among nonprofits. It is based on Project Largo, a WordPress theme developed by the Investigative News Network. And that’s an extension of National Public Radio’s Project Argo. The Lens will work with the network to help improve the Largo theme and lower the costs of high-quality publishing for other sites. The Lens thanks the network for extensive technical guidance throughout the process, as well as Assembled, which designed the site and our new logo, and Carrollton Group, which coded everything.

The Lens is now one of nine sites to adopt Largo since we launched last fall including INN members Connecticut Health I-Team, Iowa Watch and the Midwest Center for Investigative Reporting, Newsdesk.org and Pinetree Watchdog.

We'll be launching more sites very soon and we're excited about the next phase of work we're doing on the platform with our first public launch scheduled for late March or early April.

In the meantime, feel free to peruse our code on github and if you or your organization is interested in a demo or have any questions about Largo please get in touch using our contact form and we'd be happy to help you out.

Connecticut Health I-Team Launches First Site Using New INN WordPress Platform

Posted on by Adam Schweigert

The Investigative News Network is excited to announce the launch of the first website built as part of the Largo Project, a WordPress starter theme developed by INN for members with longform, investigative reporting in mind. This past Wednesday, the Connecticut Health Investigative Team (C-HIT) launched their new website at http://c-hit.org.

INN’s Director of Technology Adam Schweigert developed the project, and has been working with C-HIT Editor Lynne DeLucia to move the organization’s site onto the new content management system.

Largo incorporates a number of features from NPR's Project Argo, while significantly expanding the project to make it easier to set up and manage, adding flexibility to better support the needs of a variety of news publishers. Some of Largo's features include a mobile-friendly responsive design, three pre-built homepage layouts, highly-configurable responsive navigation menus and sidebars, built-in support for receiving donations, social media links, custom bylines and author profiles, analytics and additional functionality that would otherwise require additional plugins.

“Adam really took the time to see our mission and then put a lot of thought into tailoring the site so it showcases our investigative work,” DeLucia said. “The feedback so far has been terrific.”

Presentation of longform journalism was a priority. Largo includes formatting for pull quotes and asides, responsive images, slideshows and videos, and support for a variety of other embedded content. Articles can be broken into multiple pages, and heading and body text are optimized for readability on desktop and mobile devices. Social media support is built in, including Open Graph, Twitter Card, and Google authorship markup to ensure optimal presentation of content when it’s shared on the web. Largo also includes a curated list of plugins for additional functionality, so that news organizations can further fit the theme to their specific needs.

“INN’s members create powerful journalism every day,” said Schweigert. “We hope to put powerful publishing tools into the hands of every INN member who wants them, and to continue to grow and develop the platform to make it easier for members to build a digital presence to highlight their work.”

INN members the Midwest Center for Investigative Reporting, the Iowa Center for Public Affairs Journalism, and several others will also soon be launching websites with Largo.

Largo Project was funded in part by a generous grant from Karin Winner, board member at the Investigative Newsource.

"A great strength of INN is to help fledgling journalism nonprofits get off the ground by providing tools not only to do their job but to link members so they can learn from each other," said Winner. "A solid, interactive website will be essential to [journalism nonprofits'] ultimate success."

The code for Largo is open source, and available on Github. INN also offers assistance to its members interested in using it, and those considering a content management system or website update within the next year should contact Adam Schweigert at adam@inn.org for a demonstration.

More information about the Largo Project is available at http://largoproject.org.

Project Largo Beta Released

Posted on by Adam Schweigert

Project Largo is a WordPress framework developed for members of the Investigative News Network (INN) based on NPR's Project Argo.

As we wrap up work on the first public release of this framework we have made a beta version available on github. We will be working with a couple of INN members over the coming weeks to work out any kinks in this beta version but in the meantime we welcome your feedback.

If you would like more information or are interested in receiving updates about the project please leave a comment on this post, ask questions in our Q&A section or fork our code on github and help us make Project Largo even better.

We will also be updating and expanding this site in the coming weeks to include complete documentation for how to setup, customize and use the Largo framework for your site.