I have a web application with some "Help" buttons which point to my online documentation. The links to the help sections are hardcoded in the app database. Previously, the documentation was made in HTML and JS, and I could control the URLs to the section manually.
However, now that I am migrating to Sphinx and ReST, I found the automatic section URL generation great, but cannot figure out how to control this behaviour for my structure.
Is there a way to have a sort of URL alias which point to the actual URL of my documentation in order not to update the hardcoded links in the app db everytime I update the name of my chapters/sections?
For instance:
I have a subsection called "I like apples" in Chapter 1.
My hardcoded link to it would be something like
"Chapter1#I-like-apples" (I only care about the part following the #
sign)
I change the title to "I hate apples". The new link would become "Chapter1#I-hate-apples", but in my db I still need to have "#I-like-apples" which point to the same section.
See Hyperlink Targets in the docutils documentation, specifically "internal hyperlink targets".
.. _my-target:
.. _synonym-to-my-target:
My Subsection
-------------
Sphinx will generate targets for each synonym.
You could also do indirect hyperlink targets.
.. _my-target: synonym-to-my-target_
.. _synonym-to-my-target:
My Subsection
-------------
Related
Hugo's one-file->one-page model is nice and simple, especially for a blog. But sometimes you want to write an "article" for a blog and split it into 2 or more pieces for separate pages (perhaps to be posted on separate days, or whatever).
Is there a way to do this within Hugo? Perhaps a combination of something you put in a layout/theme/shortcode and internal markup within the page (to signal where to split the article)?
Possible models might include:
1 input post "splits" into 2/3/4 posts when the site is built to public
1 input post is duplicated into 2/3/4 posts when the site is built to public but somehow each duplicate isn't an exact duplicate but instead has the whole post but certain parts of the post are hidden/invisible, via CSS, such that they represent the 2/3/4 "pages" of the post.
Or, is this something you do external to Hugo?
UPDATE: I can see I need to clarify this. Consider this random illustrative blog post - it is the third of three closely related posts, and even has a set of links at the top so you can find the earlier posts in the series. Lots of technical blogs do this sort of thing (at least the ones I read).
Now, I'm not looking for a CMS or anything complex. What I do now with Hugo is hugo new posts/an-article-about-constexpr.md and I write one markdown file and it becomes one "post" in standard Hugo fashion. Exactly what you want a SSG to do.
What I want to do is write one markdown file but have some kind of markup in it separating it into sections (like <!-- More --> on steroids) so that instead of generating one page of my site it generates three (in this example) - three separate articles with links from the main page in the "posts" section, etc. etc. And for bonus points, I'd like to generate these "table of contents" sections with links to each of the pages.
So I've been doing that with a cobbled-up awk script that generates pages right next to the post, in the posts directory. I set the post to draft so it doesn't get published, but the pages generated by the awk script have draft=false so they do get published. And the dates get set so they're "in order".
And that's working, but before I invest more time in my little script, I wanted to see if there was a proper way to do this within hugo.
Not sure what you mean by one-file->one-page model.
I have very few parts of any hugo site which one markdown file=one rendered html page.
Could just be the way I build, but everything I've done so far has been vanilla hugo.
To answer your question: Yes, you are correct that would work. There a few ways to do this (I list one below), but maybe a deeper look would be separating the concept of a "tool-chain" and what Hugo is in that tool chain, from a CMS, which Hugo is not.
So, to possibly answer your specific question though:
You can store content in markdown, markdown front matter, or a Data form (XML/JSON) in hugo. Using the page resources {{ .GetPage }} you can access any content and load it in any template or using shortcodes, load it in other markdown.
If I needed to do this as part of a tool chain, i.e. use specific markdown and re-use it in multiple places, I would create a front matter variable, or taxonomy or tag depending on what groupings I needed where, so this was scalable. params such as
"articleAuthor: Jessie P."
"date: DATE HERE"
"tags: etc. etc."
Then lets say I know that's going to be a blog, well fine, then it will be in the corresponding content folder, but if I needed all of Jessie's articles, or articles on that date, or that specific article, I would use the shortcode I make or directly in a template, using .GetPage Match - import the markdown pages I need based on the parameters I need.
But on the other hand, I would need to understand the problem being solved, but, here are a few hugo docs to help you out:
https://gohugo.io/functions/getpage/#readout
https://gohugo.io/content-management/page-bundles/
Remember, Hugo is not a CMS, it is a site generator. If you want a CMS, you can always use Wordpress headless, or any other solution out there.
(off the top of my head using page bundles)
{{ $headlessBundle := .Site.GetPage "/blogs/specific-blog/index" }}
{{ with $getContent := $headlessBundle.Resources.Match "intro.md" }}
{{ (index $getContent 0).Content }}
(You would use various "Where" statements to "filter" content based on the params or however you delineate what you want).
Or for instance if I wanted only the text that had an H1 tag:
{{ $.Scratch.Set "summary" ((delimit (findRE "(<h1.*?>.*?</h1>\\s*)+" .Content) "[…]") | plainify | replaceRE "&" "&" | safeHTML) }}
{{ $.Scratch.Get "summary" }}
Based on the update to the question:
https://discourse.gohugo.io/t/split-markdown-content-in-two-files-but-dont-render-shortcodes-as-raw-text/32080/2
https://discourse.gohugo.io/t/getting-a-list-from-within-a-shortcode/28126
https://discourse.gohugo.io/t/splitting-content-into-sections-based-on-header-level/33749
https://discourse.gohugo.io/t/multiple-content-blocks-on-a-single-page/9092/3
jrmooring answered it best in the above with clear examples and code.
Though, note: If I was doing this in a technical blog this would be integrated into the CMS and coordinated with the builder.
I'm creating a Sphinx documentation and I struggle to identify the "proper" way to set up the structure and links.
STRUCTURE 1#
Currently, my structure looks as below:
index.rst
about-manual/index.rst
Inside my root index.rst, the toctree is as below:
===========================
Contents
===========================
.. toctree::
about-manual/index
This results in the below links:
https://example.com/docs/ --> Content of index.rst
https://example.com/docs/about-manual --> Content of about-manual/index.rst
This works as intended in terms of link resolution
However, I'm unsure if it's the "proper" way of setting up my Sphinx structure
STRUCTURE 2#
index.rst
about-manual.rst
Inside my root index.rst, the toctree is as below:
===========================
Contents
===========================
.. toctree::
about-manual
This results in the below links:
https://example.com/docs/ --> Content of index.rst
https://example.com/docs/about-manual --> ERROR
https://example.com/docs/about-manual.html --> Content of about-manual.rst
This results in a more compact/simple Sphinx structure
However, if a user enters an URL without explicit .html at the end, the link is broken
Am I missing a basic configuration setting in Sphinx in order to make the link resolution work as per my expectation with 'STRUCTURE 2#' - without having to add the explicit .html at the end?
And is it possible to avoid having the Sphinx documentation explicitly resolve to the index.html at the end of an URL path? It does this as expected on the root index, but in 'STRUCTURE 1#' all sub pages explicitly show the index.html at the end.
I've looked at html_file_suffix and html_link_suffix, but I've not been able to make these work for my purpose either.
I found a solution for this by using sphinx-build -b dirhtml instead of sphinx-build -b html (as proposed by Jesse Tan from the sphinx_rtd_theme team) - for details see this link.
It basically lets me use the approach in 'STRUCTURE 2#', but it builds the output with an index.html files structured in folders named as per the .rst files.
Importantly, the internal links are also updated to not include the index.html part.
I am trying to add links in the form 555-555-555 arbitrarily into paragraphs of text on my wagtail site. These phone numbers are currently peppered throughout the site as plain text, but I want to convert them to links.
I found this old wagtail github issue where they explained why they would not add them, but the 'Special-purpose pages' use case they described seems to be different than mine: my site has these numbers in paragraphs of text on most of the content pages (blog, product, marketing, etc).
Can anyone explain how I can add telephone links that can be used throughout the site?
I am using wagtail 1.x
To have telephone link within rich text, you'll need to create a plugin for Hallo.js. Have a look at the documentation and how Wagtail 1.13 creates and register such plugins.
Be aware though that it's usually quite involved and that Wagtail 2.0 rich text editor is now Draftail and Hallo.js is deprecated. Therefore, if you create a Hallo.js plugin and upgrade to Wagtail 2.0, you'll have to add some configuration to continue using Hallo.js or recreate the plugin for Draftail.
FWIW, if you are interested in having a look at what would be involved with creating an plugin for Draftail, you'll need to create an entity (also note that the API for creating entities should receive some enhancements in Wagtail 2.2).
With Raw HTML there is nothing to prevent editors from inserting malicious scripts into the page. Do not use this block. http://docs.wagtail.io/en/v2.1/topics/streamfield.html#rawhtmlblock
A workaround would be a custom filter. Eg:
{{ self.text|richtext|phonify }}
In your templatetags.py:
>>> def phonify(val):
... for tel in re.findall(r'tel:(\d+)', val):
... tag = '{}'.format(tel, tel)
... val = val.replace('tel:{}'.format(tel), tag)
... return val
...
>>> phonify('Hello tel:123 world tel:456!')
'Hello 123 world 456!'
>>>
Now you can instruct editors (via help_text) to add phone numbers like tel:5555555555.
This example does not handle - and +1. But if you figure that out, I'll update the answer ;)
I ended up chopping up my paragraphs and including raw html where I needed to add the tel links. A bit tedious, and the styles were slightly different on some pages, but shorter than doing it any other way.
Lets say I have Project A with an attached imageFile.
Then I created 10 different Projects which are underprojects of Project A.
I want to link the ImageFile of Project A to the Wiki of every underproject , so that I can see the ImageFile in the Wiki-Area of each underproject.
What im doing so far is to copy full path of the attached file of Project A in the Wiki of every underproject, like for example:
!>/attachments/download/157/schnittprofil.png!
Is there a better way to achieve that, because every time I update the imagefile, I have to renew the id-numbers of all imagefile-links in the underprojects.
Since an attachment is only actually identified by its ID and all attachments are immutable (i.e. can be changed after upload), new uploads will result in a new ID. Since multiple attachments with different IDs can have the same name, you can also not reliably find an attachment just by using its name in broad contexts.
That said, to solve your issue, you could use the include macro to include a common Wiki page in your sub-project's wiki pages which then displays the image attachment.
For that, you can create a Wiki page named e.g. Schnittprofil in your parent project where you directly upload your file. In the wiki page, just reference the image with
!schnittprofil.png!
Assuming the parent project has an identifier of project-a, you can then include the page in other wiki pages with
{{include(project-a:Schnittprofil)}}
Each time you change the page on the parent project, it will automatically also show the updated content on the child wikis. The only requirement is that the users need to be able to read the wiki of your parent project (e.g. are members of the project with the "Read wiki" permission).
I'm currently making a bilingual Expression Engine 2.5.2 website. I'm using this technique to create the two langues, which works perfectly.
I have created a {country_code} global variable in the two index.php files which allows me to detect the current language.
Using this technique, I have no problems to get language-relative data when accessing an entry. My only concern is that I apparently have to privilege a language-specific "clean" URL.
Example entry:
{entry_id} = 123
{title} = My test article
{title_permalink} = my-test-article
{name_fr} = Mon article
{name_en} = My article
If I request http://www.example.com/index.php/en/blog/articles/my-test-article, I expect to to find, in english, "My article" using the template articles in the blog template group.
Everything is fine, but the french translation is accessible when requesting http://www.example.com/index.php/fr/blog/articles/my-test-article. The correct translation of the URL should be http://www.example.com/index.php/fr/blogue/articles/mon-article-test.
Anyone encountered a problem like this? Any solutions via extensions or modules?
I believe the Transcribe module solves this by both providing the ability to translate template group and template names, and having you create a separate entry for each language and piece of content in your site (hence, you have two separate URL titles). But that means buying into their entire methodology for a multi-lingual site.
Myself, I usually just stick to using the entry_id instead of the url_title, and live with the template names being in the primary language.
The best way I found to achieve this is by embedding templates with segment translations, duplicating template groups and duplicating channels.
In the blog/articles template:
{embed="shared/.head" segment_2_translation="blogue" segment_3_translation="articles"}
In the blogue/articles template:
{embed="shared/.head" segment_2_translation="blog" segment_3_translation="articles"}
In shared/.head template:
[...] {if lang == "fr"}English{if:else}Français{/if} [...]
And then you can create a Articles (FR) and a Articles (EN) channels, and each will have their unique URL titles. You can also add a relationship custom field for each channel to associate an entry with it's translation.
It feels messy, but it is the only way I could make it work without modules, plugins or whatnot.