Metadata-Version: 2.0 Name: anchorhub Version: 0.13 Summary: Easily utilize GitHub's automatically generated anchors within and across Markdown documents Home-page: https://github.com/samjabrahams/anchorhub Author: Sam Abrahams Author-email: sam@samabrahams.com License: Apache 2.0 Keywords: markdown anchor links processing Platform: UNKNOWN Classifier: Intended Audience :: Developers Classifier: Topic :: Software Development :: Pre-processors Classifier: License :: OSI Approved :: Apache Software License Classifier: Programming Language :: Python :: 2.7 Classifier: Programming Language :: Python :: 3.3 Classifier: Programming Language :: Python :: 3.4 Classifier: Programming Language :: Python :: 3.5 Requires-Dist: nose .. figure:: img/graphic.png :alt: AnchorHub graphic AnchorHub graphic AnchorHub ========= **AnchorHub** is a command-line tool that makes it easy and intuitive to utilize GitHub's auto-generated anchor tags in your `Markdown `__ documents, allowing you to create rich, user-friendly documentation in your GitHub repos without having to figure out what those auto-generated tags will be. Features -------- - Easily link to sections of Markdown documents on GitHub - Simple, customizable syntax that just works - Works within the entire directory tree automatically -------------- `Table of Contents `__ \| `FAQ `__ \| `About AnchorHub `__ -------------- Installation ------------ You can install AnchorHub using `pip `__: :: $ pip install anchorhub Quick Start Guide ----------------- Inside your Markdown files, define and use header anchors like the following: .. # This is a header that I would like to make an id for {#head} [This link points to that header!](#head) Navigate to the root of the directory tree you'd like to process and type: :: $ anchorhub . This will output your processed files in a new folder in your current directory, 'anchorhub-out'. The output of AnchorHub on the Markdown written above is this: .. # This is a header that I would like to make an id for [This link points to that header!](#this-is-a-header-that-i-would-like-to-make-an-id-for) Using AnchorHub =============== This section goes over how to write your Markdown files in order to utilize AnchorHub, as well as how to use the command-line interface to AnchorHub. 1. `Defining anchors on header lines <#defining-anchors>`__ 2. `Using those anchors in links <#link-syntax>`__ 3. `Processing files with the ``anchorhub`` command line interface <#anchorhubs-command-line-interface>`__ Defining Anchors ---------------- Place identifiers with a leading '#' inside of ``{ }`` wrappers at end of header lines you'd like to reference. For example: .. # This is the header I'd like to create an anchor for {#head} *Note: You can specify your own style of wrappers if ``{ }`` braces don't suit your needs. `See below <>`__ for an example.* Link Syntax ----------- Write links to your specified anchors as if you had created an HTML element with an ``id`` or ``name`` parameter: .. In the middle of this sentence, I'd like to link back to [the header specified above](#head) AnchorHub automatically automatically works for all files within a directory tree, so if you had a file named 'other.md' with '#ref' defined as an anchor, you can link to it from your original file without any additional effort: .. code:: markdown Let's link to that [other file's anchor!](other.md#ref) *Note: Make sure you use AnchorHub on the highest-level directory that you'd like to process. AnchorHub will search in all sub-directories of the input directory, but it will never step backwards. `See below <>`__ for details.* AnchorHub's Command Line Interface ---------------------------------- Usage ~~~~~ .. anchorhub [-h] [-v] [-X] [-e EXTENSIONS [EXTENSIONS ...]] [-w WRAPPER] input [output] Input ~~~~~ The only required argument to ``anchorhub`` is the desired input root. AnchorHub will walk through all subdirectories within the input and process all Markdown files it finds. .. $ anchorhub path/to/my/input Output ~~~~~~ The second argument, if provided, specifies the desired output directory. By default, AnchorHub will output to ``anchorhub-out`` within the present working directory. Regardless of where the output is located, the structure of the output directory will match that of the input directory. .. $ anchorhub input path/to/my/output Options ~~~~~~~ **-h / --help:** Display the terminal help prompt for ``anchorhub`` .. $ anchorhub -h **-v / --version:** Display the installed version of ``anchorhub`` .. $ anchorhub -v **-X / --overwrite:** Instead of outputting to a separate directory, overwrite the input files .. $ anchorhub -X ./input **-e / --extension EXTENSION [EXTENSIONS ...]:** Process files that end with the provided extensions The default value is ``".md"``. You can provide multiple extensions if you have files that use various extensions: .. $ anchorhub ./input -e .md .markdown .MD **-w / --wrapper:** Specify the wrapper syntax for defining anchors The default value is ``"{ }"``. Make sure you have a space between your opening and closing patterns and to wrap the whole thing in quotation marks: .. $ anchorhub ./input -w "[--> <--]" Additional Info =============== Examples -------- Single file ~~~~~~~~~~~ Input ^^^^^ .. # This is the top of my document! {#top} Going to have some more cool text explaining stuff. Skip to features header with [this link!](#features). ## Here is my feature list! {#features} * Gotta have some bullet points! * Let's keep it up! * This bullet point is here for the rule of three [Link back to the top!](#top) Output ^^^^^^ .. # This is the top of my document! Going to have some more cool text explaining stuff. Skip to features header with [this link!](#here-is-my-feature-list). ## Here is my feature list! * Gotta have some bullet points! * Let's keep it up! * This bullet point is here for the rule of three [Link back to the top!](#this-is-the-top-of-my-document) Multi-file ~~~~~~~~~~ AnchorHub automatically looks at the entire directory tree when checking for anchor matches, so you can link to other documents in the same fashion. Each file has its own distinct set of anchors, so you can reuse the same tags on different pages. Here's a super simple demonstration below: Input ^^^^^ file1.md .. # Some header for this file {#go-here} [Link to another file's header](dir/file2.md#awesome) dir/file2.md .. # The awesome header in file2.md {#awesome} [Link back to file1.md](../file1.md#go-here) Output ^^^^^^ file1.md .. # Some header for this file [Link to another file's header](dir/file2.md#the-awesome-header-in-file2md) dir/file2.md .. # The awesome header in file2.md [Link back to file1.md](../file1.md#some-header-for-this-file) To-do List ---------- - Support for reference-style Markdown links - Support for Setext ("underlined") style headers - Verify cross-platform compatibility (currently only tested on OSX) - Proper exception handling - Support for ReStructuredText - Support for arbitrary generated anchor styles (not just GitHub-style) - Clean, refactor, reorganize - More tests! Known Issues ------------ - Should not change text within in-line code (those marked by \` backticks) License ------- :: Copyright 2016, Sam Abrahams. All rights reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. `Back to top <#anchorhub>`__