racket/scribble

Add "Edit Online" button

Open

#76 opened on Jan 23, 2017

View on GitHub
 (11 comments) (2 reactions) (0 assignees)Racket (102 forks)github user discovery
help wanted

Repository metrics

Stars
 (250 stars)
PR merge metrics
 (Avg merge 12h 51m) (1 merged PR in 30d)

Description

Goal: pages on docs.racket-lang.org should have a button labeled "Edit on GitHub" that opens the scribble file that generated the HTML file that's displaying the button.

This is an issue and not a PR because I'm not sure how to implement it.

Idea 1 (the dream) change Scribble to automatically add "edit on github" links to the drop-down that appears when you click headings (just below "link to this section"). Guess this would only work for cloned packages.

Idea 2 (the less-wild dream) implement a --github <url> flag for the scribble command that uses the given url to generate the "edit on github" links for every page title / section.

Idea 3 (the easy-to-hack) put an @github-link[url] function in a scriblib library. Documentation authors need to explicitly call this function to put a button on their pages. (Instead of a button, maybe add a keyword to @section or @title)

Contributor guide

Research direction
Explore Scribble's source code to understand how headings and sections are rendered. Look for existing mechanisms like the drop down menu and consider how to integrate an 'Edit on GitHub' link. Evaluate the feasibility of each proposed idea by examining the relevant modules and documentation.
Tech stack
None
Domain
documentationtooling
Issue type
Feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
Half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Mostly clear
Prerequisites
RacketScribble
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
45