Merge pull request #1071 from talha131/change-intrasite-link-syntax-updated

Change intrasite link syntax updated

docs/changelog.rst

@@ -9,7 +9,8 @@ Next release
   longer article-specific
 * Deprecate ``FILES_TO_COPY`` in favor of ``STATIC_PATHS`` and
   ``EXTRA_PATH_METADATA``
-* Add support for |tag| and |category| relative links.
+* Add support for ``{}`` in relative links syntax, besides ``||``
+* Add support for |tag| and |category| relative links
 
 3.2.1 and 3.2.2
 ===============

docs/getting_started.rst

@@ -390,6 +390,8 @@ If you want to exclude any pages from being linked to or listed in the menu
 then add a ``status: hidden`` attribute to its metadata. This is useful for
 things like making error pages that fit the generated theme of your site.
 
+.. _ref-linking-to-internal-content:
+
 Linking to internal content
 ---------------------------
 
@@ -400,7 +402,7 @@ and images that may be sitting alongside the current post (instead of having
 to determine where those resources will be placed after site generation).
 
 To link to internal content (files in the ``content`` directory), use the
-following syntax: ``|filename|path/to/file``::
+following syntax: ``{filename}path/to/file``::
 
 
     website/
@@ -421,8 +423,8 @@ In this example, ``article1.rst`` could look like::
 
     See below intra-site link examples in reStructuredText format.
 
-    `a link relative to content root <|filename|/cat/article2.rst>`_
-    `a link relative to current file <|filename|cat/article2.rst>`_
+    `a link relative to content root <{filename}/cat/article2.rst>`_
+    `a link relative to current file <{filename}cat/article2.rst>`_
 
 and ``article2.md``::
 
@@ -431,8 +433,8 @@ and ``article2.md``::
 
     See below intra-site link examples in Markdown format.
 
-    [a link relative to content root](|filename|/article1.md)
-    [a link relative to current file](|filename|../article1.md)
+    [a link relative to content root]({filename}/article1.md)
+    [a link relative to current file]({filename}../article1.md)
 
 Embedding non-article or non-page content is slightly different in that the
 directories need to be specified in ``pelicanconf.py`` file. The ``images``
@@ -447,7 +449,7 @@ manually::
 
 And ``image-test.md`` would include::
 
-    ![Alt Text](|filename|/images/han.jpg)
+    ![Alt Text]({filename}/images/han.jpg)
 
 Any content can be linked in this way. What happens is that the ``images``
 directory gets copied to ``output/static/`` upon publishing. This is
@@ -459,9 +461,16 @@ following to ``pelicanconf.py``::
 
 And then the ``pdfs`` directory would also be copied to ``output/static/``.
 
-You can also link to categories or tags, using the `|tag|tagname` and
-`|category|foobar` syntax.
+You can also link to categories or tags, using the ``{tag}tagname`` and
+``{category}foobar`` syntax.
 
+For backward compatibility, Pelican also supports bars ``||``, besides ``{}``,
+i.e. the ``filename``, ``tag`` and ``category`` identifiers can be enclosed
+in bars ``|`` instead of braces ``{}``, for example, ``|filename|an_article.rst``,
+``|tag|tagname``,  ``|category|foobar``.
+
+Using ``{}`` ensures that the syntax will not collide with markdown extensions or
+reST directives.
 
 Importing an existing blog
 --------------------------

docs/settings.rst

@@ -156,6 +156,11 @@ Setting name (default value)                                            What doe
                                                                         <http://www.methods.co.nz/asciidoc/manpage.html>`_
 `WITH_FUTURE_DATES` (``True``)                                          If disabled, content with dates in the future will get a
                                                                         default status of draft.
+`INTRASITE_LINK_REGEX` (``'[{|](?P<what>.*?)[|}]'``)                    Regular expression that is used to parse internal links.  
+                                                                        Default syntax of links to internal files, tags, etc. is 
+                                                                        to enclose the identifier, say ``filename``, in ``{}`` or ``||``.
+                                                                        Identifier between ``{`` and ``}`` goes into the ``what`` capturing group.
+                                                                        For details see :ref:`ref-linking-to-internal-content`.
 =====================================================================   =====================================================================
 
 .. [#] Default is the system locale.

pelican/contents.py

@@ -182,13 +182,15 @@ class Content(object):
         if not content:
             return content
 
-        hrefs = re.compile(r"""
+        instrasite_link_regex = self.settings['INTRASITE_LINK_REGEX']
+        regex = r"""
             (?P<markup><\s*[^\>]*  # match tag with src and href attr
                 (?:href|src)\s*=)
 
             (?P<quote>["\'])      # require value to be quoted
-            (?P<path>\|(?P<what>.*?)\|(?P<value>.*?))  # the url value
-            \2""", re.X)
+            (?P<path>{0}(?P<value>.*?))  # the url value
+            \2""".format(instrasite_link_regex)
+        hrefs = re.compile(regex, re.X)
 
         def replacer(m):
             what = m.group('what')

pelican/settings.py

@@ -110,6 +110,7 @@ DEFAULT_CONFIG = {
     'TEMPLATE_PAGES': {},
     'IGNORE_FILES': ['.#*'],
     'SLUG_SUBSTITUTIONS': (),
+    'INTRASITE_LINK_REGEX': '[{|](?P<what>.*?)[|}]',
     }