I am trying to insert an inline image into an .rst file, with no success. I've tried replicating the syntax used by the previous tech writer, as follows:
|icon-copy|
The name of the image file referenced by the above syntax is studio_icon_copy. However, creating an image file called studio_icon_additional, and using the |icon-additional| syntax, doesn't work. I verified that this is the syntax used for all working instances of inline images.
I have also verified that the studio_icon_copy in the folder I'm using is indeed the right image by making a slight change to it and verifying that I see the change on the front end. I've also made sure that the new image I've created is in this same folder.
I've even tried copying and pasting the correct syntax in the desired place and simply replacing copy with additional, which didn't work either.
For what it's worth, I use Notepad++ and work in GitHub. After trying the above I have no clue how to insert it correctly, although I'm pretty sure I'm missing something.
Thank you.
Actual quote from https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions says:
The |biohazard| symbol must be used on containers used to
dispose of medical waste.
.. |biohazard| image:: biohazard.png
This should be actually this way:
.. |biohazard| image:: biohazard.png
The |biohazard| symbol must be used on containers used to
dispose of medical waste.
Always declare |pic| before referencing to it. I think there were some changes to that and documentation wasn't actually updated. You can always add option to make it really small, then you've got certainty that it will look good next to text:
.. |biohazard| image:: biohazard.png
:height: 25px
Related
I am writing lots of Sphinx/RestructuredText and this includes Sequence Diagrams using PlantUML. I have lots of text that I am reusing, so to make things cleaner, I created a definitions.iuml file. In this file, I can create named text references (via !startsub/!endsub blocks) that allows me to reference them in several different Sequence Diagrams. Change it once in the source location, and they all change. Perfect.
My problem is how to use these references outside of Sequence Diagrams? I use the exact same code (!includesub ../defintions.iuml!NAMED-REFERENCE) in the .rst file, and when I make docx/pdf, I see that link, I don't see the text that it is referencing. To make things worse, Google has like no documentation or search results on this. Queries of includesub, startsub, endsub +sphinx come back with nothing.
Help me obiwan kenobi.
I found the answer, which only resulted in more questions haha. Anyway, one thing at a time:
To create reference variables in your text document, use rst_prolog or rst_epilog in your Conf.py file. Why there are 2 commands that serve the same purpose, I dont know.
rst_prolog = """
.. |Variable1| replace:: Monday
.. |Variable2| replace:: Tuesday
"""
Now whenever you write |Variable1| in your text, the document will generate Monday.
The problem with the above is that its just for short words/phrases. You can't use it for code blocks, or anything that is more than one line. To reference in Code Blocks:
Create a new .rst file with the code you want to display. Best practice is to create a Code folder and place them all in there.
Further best practice is to stop using the '.. code block::' and instead use '.. parsed-literal::'. The output is the exact same, but parsed-literal allows you to use conf.py variables and ..codeblock:: doesn't.
So in this .rst file, first line is .. parsed-literal:: and all the text below it is the code you want to reference
In the original document that you wanted this code, type:
<4 spaces indent>.. include:: <Folder/File.rst>
Generate your document, and notice how the code is now being reference. You can include this reference all throughout your document.
I will soon be creating a new thread, this time asking how the text body and sequence diagrams can use the same reference. Currently, all text needs one reference, all sequences need another reference, and now we have double updates. Not ideal
In markdown I can write:
[example1][myid]
[example2][myid]
[myid]: http://example.com
so I don't have to retype the full external link multiple times.
Is there an analogous feature in AsciiDoc? Specially interested in the Asciidoctor implementation.
So far I could only find:
internal cross references with <<>>
I think I saw a replacement feature of type :myid:, but I can't find it anymore. And I didn't see how to use different texts for each link however.
Probably you mean something like this:
Userguide Chapter 28.1. Setting configuration entries
...
Attribute entries promote clarity and eliminate repetition
URLs and file names in AsciiDoc3 macros are often quite long — they break paragraph flow and readability suffers. The problem is compounded by redundancy if the same name is used repeatedly. Attribute entries can be used to make your documents easier to read and write, here are some examples:
:1: http://freshmeat.net/projects/asciidoc3/
:homepage: http://asciidoc3.org[AsciiDoc3 home page]
:new: image:./images/smallnew.png[]
:footnote1: footnote:[A meaningless latin term]
Using previously defined attributes: See the {1}[Freshmeat summary]
or the {homepage} for something new {new}. Lorem ispum {footnote1}.
...
BTW, there is a 100% Python3 port available now: https://asciidoc3.org
I think you are looking for this (and both will work just fine),
https://www.google.com[Google]
or
link: https://google.com[Google]
Reference:
Ascii Doc User Manual Link
Update #1: Use of link along with variables in asciidoc
Declare variable
:url: https://www.google.com
Use variable feature using format mentioned above
Using ' Link with label '
{url}[Google]
Using a relative link
link:{url}[Google]
In a Maven project with subprojects, each subproject gets an index.html with some content that comes from its POM's description element.
In one of these subprojects, I need that content to contain additional information, including links. There is a section of the doc that suggests I should not do it by trying to put HTML markup in CDATA in the description element (in fact, that doesn't work anyway; the HTML markup just comes out literal). Instead, it suggests there is some better way to get my own content included in the file.
While this element can be specified as CDATA to enable the use of HTML tags
within the description, it is discouraged to allow plain text representation.
If you need to modify the index page of the generated web site, you are able
to specify your own instead of adjusting this text.
Can anyone describe how to do that? I have tried several methods unsuccessfully (I can supply Markdown files with other names and they generate HTML, but a subproject's index.md has no effect on the generated index.html). I have also read about the custom element in site.xml but it seems to require writing a custom Velocity template for the site; I hope the passage "you are able to specify your own" must mean there is some method more straightforward than that.
Of course I would also appreciate a pointer into the docs if there is already an answer I have simply failed to find. (Just pointing me to docs I've already read isn't in itself helpful, though pointing out the answer I missed would be helpful, if it's there.)
In response to inquiries
Directory structure under src/site:
src/site
src/site/resources
src/site/resources/images
src/site/markdown
src/site/markdown/use
src/site/markdown/install
src/site/markdown/examples
src/site/markdown/build
maven-site-plugin version: 3.4
What I mean by 'adding a link':
The part of the index.html that comes from the POM description element
is the central content of the page (not the navigation bar, not the sidebar menus, but the actual content).
I would like that actual-content portion of the page to be able to have a paragraph or two explaining that this is a generated page for developers, and providing links (HTML <a href=...>) for people who arrived at the page from a web search but are really looking for the user-oriented pages.
I can't put that in the description element (even using CDATA), because HTML elements just come out literal. A comment below gives a link to a page on writing a whole custom Velocity template for the site, but is there honestly no simpler way to accomplish this?
I have the same issue. The only thing the generated index.html gives you of value is the list of modules. You can add your own index.md page to src/site/markdown, putting in whatever content you want. To reproduce the list of modules, include something like this:
###Project Modules
This project has declared the following modules:
| Name | Description |
|-|-|
|[Module1 name](module1/index.html)| Module 1 description|
|-|-|
|[Module2 name](module2/index.html)| Module 2 description|
Of course the text is not lifted from the POM. You also have to manually change this file if you have a new module. Not a perfect solution, but the best I could come up with.
Where I wrote:
I can supply Markdown files with other names and they generate HTML,
but a subproject's index.md has no effect on the generated index.html
it turns out the truth is more complex. In a project with subprojects,
there are two places such an index.md might go: in src/site/markdown/subproject-name of the parent project (where all of the other human-written docs for the whole project happen to be), or in a new src/site/markdown directory created within the subproject. A file with any other non-special name can be added in either place, and end up where you expect it in the target. But not for index.md, in that case only the second location can work, and even then, only after a clean.
I had tried both places without success, but trying the second again with a full clean install site site:stage makes it work. Out of the four combinations (parent/clean, parent/noclean, sub/clean, sub/noclean), that was the one I missed trying before posting the question, so of course that's the one that works. :)
If there had been an answer or comment like "hmm, are you sure an index.md in the subproject doesn't work, it works for me?" it probably would have put me quickly back on track. Sometimes after trying several avenues all without success, all that's needed is to know which of them is the one that's supposed to work (if indeed one of them is) and therefore worth spending more time on.
Revising the title since I figured out that the problem was totally different than what I thought it was. Should I delete this question or leave it out here in case someone else makes this same mistake?
Original title was: Some Sphinx cross-references don't recognize section title?
Original question:
I'm seeing some really odd behavior - I have cross-references in my Sphinx markup according to http://sphinx-doc.org/markup/inline.html#ref-role
but when I build the document (HTML or LaTEXPDF) I get these errors on some of them:
WARNING: undefined label: _unhiding (if the link has no caption the label must precede a section header)
Thing is, the working and nonworking ones look exactly the same to me.
Working:
.. _conditions:
Monitoring Conditions and Alerts
================================
Broken:
.. _performance:
Viewing System Performance
==========================
Also broken:
.. _unhiding:
Unhiding Conditions and Canceling Auto-Dismiss
-----------------------------------------------
I even copied the working one and replaced the reference term, but that didn't help.
I should be able to work around this by explicitly defining the captions, but this is mystifying....
AUGH! Never mind, the title warning was a red herring.
The problem was in the references - I was including the _ in the reference text, but it's secretly not part of the key. I forgot this since I used references a few weeks ago and it's not obvious from the documentation.
Doesn't work:
:ref:`_unhiding`
Does work:
:ref:`unhiding`
Did a MediaWiki upgrade from 1.15.1 to 1.20.2 by following the simple update instructions (basically a new installation, copying over the old LocalSettings.php, update script and copying over images). Weird thing now is that all of the File: prefixes don't work. Instead the internal links to images is a "file:name of image" URL rather than "http://mediawiki address/index.php/File:name of image".
Anybody else getting this. Assuming it is something wrong with the old LocalSettings.php.
Ran the refreshLinks and refreshImageMetadata maintenance scripts without fixing the problem.
In the comments, you wrote that you have file: added to $wgUrlProtocols. This is very likely what's triggering the problem.
It looks like something has changed in the parser between MW 1.15 and 1.20 so that it's now parsing file:whatever as an external link (since it matches the file: prefix you've defined in $wgUrlProtocols) even if it's inside square brackets.
The obvious workaround would be to change the $wgUrlProtocols entry from file: to file:// so that it will only match if the slashes are there (as they should be, according to standard file: URL syntax). Since your on-wiki filenames are, presumably, very unlikely to begin with double slashes, they should not match this more specific prefix.
That said, this could still be considered a bug in MediaWiki. You may want to file a bug report about it, if there isn't one yet.
(Edit: Looks like Mark A. Hershberger filed one already.)