I want to build a simple script that may be useful for others as well, but I have only very basic programming knowledge and can't do it myself without learning how to write powershell scripts from scratch.
What this script is supposed to do is, open an INI file (really just a txt), look for a variable with an assigned value and replace that value from a txt hosted on GitHub, save and then run a program.
This is for the tracker list of qBittorrent, since that feature still hasn't been implemented and the only other script that I could find that does this is for linux and mac, there seem to be none for windows.
The basic idea is this:
get-content "c:\users\[user]\appdata\roaming\qbittorrent\qbittorrent.ini"
# This is where pseudo code starts
get file from "[github-link.txt]"
save file to cache # keeping it is useless as it gets updated daily
find variable "Session\AdditionalTrackers=" in qbittorrent.ini
replace value of variable with content of cached file # this is what I struggle with most when looking for example code. Everything I could find specified the exact string that needed replacing, which in this case is quite long and may change with every update of the file.
overwrite original file
launch program qbittorrent.exe
end script
Conveniently or most likely deliberately all (most) of the tracker lists on GitHub are already formatted in a way that they can be directly pasted into the file without having to worry about formatting. Example.
I can totally understand if nobody wants to do the work, but I would greatly appreciate it and possibly others that are looking for a stopgap for the lacking feature.
If this already exists, go ahead and call me an idiot and while you're at it drop a link ;)
I just found a little tool called Power Automate and it pretty much does what I was looking for. It's not quite as elegant as a single click script but it does the job. Sadly I can't share the "flow" I built because, well, there is no option for it - thanks Microsoft. So, I'll try my best to write it out.
Not quite a "solution" but pretty to close to it.
Here is the "flow":
get file from web // from github for example
read text from file // read downloaded .txt file
read text from file // read qBittorrent.ini
crop text // crop between flags in qBittorrent.ini use "Session\AdditionalTrackers=" as start and "Session\GlobalMaxRatio=" as end and save to cropVar2
crop text // crop before flag use "Session\AdditionalTrackers=" as flag and save to cropVar1
crop text // crop after flag use cropVar2 as flag and save to cropVar3
replace text // replace cropVar2 with content of downloaded file and save to cropVar2
write text to file // write cropVar1,cropVar2,cropVar3
end flow
Keep in mind that any changes to the qBittorrent.ini may change the order of the entries. Which means you have to check if it's still correct after every update and after every change you make in the options. This is a massive cludge after all...
You can input fail saves so that you won't break anything if the order changed.
It happens when a user inserts a Word Document(Source) into another Word Document(Destination) - auto numbering/bullets didn't work...
I wont to insert text here, and continue auto-numbering of source as it in destination:
Step 1
But it inserting above without auto-numbering:
Step 2
I have an answer from MS that it's a feature of MS Word :(.
So, the question is - is it possible to automatically align the above either by use Word Automation ( via C# , .NET Interop Word APIs )?
I mean to align the source document contents as per the destination document’s Auto-numbering. The same is about Bullets...
Please help - we are open to any suggestions/ recommendations.
Both documents need to have the same style definitions for both the Paragraph Style of the text being copied and also the List Style that organizes the numbering or bullets. Using automation, you can copy styles between the files before actually moving the numbered or bulleted text.
I agree with John.
The basic idea is to use the Define New MultiLevel List Dialog to define a new multilevel list in which each level you would be using is attached to an existing paragraph style. A paragraph style can be attached to only one level in one list. Then use the styles to apply the numbering.
Once you have them set up, you apply the numbering by using the styles, not the numbering controls.
Setting up the numbering linked to styles can seem a bit convoluted. Step-by-step instructions for doing it in Windows can be found here:
http://www.shaunakelly.com/word/numbering/numbering20072010.html
Backup: http://web.archive.org/web/20130510174814/http://www.shaunakelly.com/word/numbering/numbering20072010.html
For a Mac, John has a page showing the Mac controls to accomplish it.
http://www.brandwares.com/bestpractices/2016/06/outline-numbering-in-word-for-os-x/
Backup link: http://web.archive.org/web/20200912134758/http://www.brandwares.com/bestpractices/2016/06/outline-numbering-in-word-for-os-x/
These describe the only known ways to have consistent numbering in Word in heavily-edited / co-authored documents.
Tl;dr;
What is the correct way to create an anchor in docbook? and is there a way that will make the anchor visible in writer?
Background
I am trying to split up documentation that was previously in single open office documents into smaller asciidoc documents which are both included in the main open office document and also converted to either or both of html & pdf.
I have this mostly working. I use asciidoctor to create html. asciidoctor-pdf to create pdf and a combination of asciidoctor and pandoc to create .odt files. I also tried the python implementation of asciidoc but found the interface less useable.
Round tripping between asciidoc and odt is obviously not possible. This is sort of a fusion where the master document is word processed but pieces of content that can be produced independently (think man pages - in fact that is one of several use cases) are included.
asciidoc to html:
asciidoctor -b html5 foo.adoc -o foo.html
asciidoc to pdf:
asciidoctor-pdf -b pdf foo.adoc -o foo.pdf
asciidoc to odt
asciidoctor -b docbook foo.adoc -o foo.docbook
pandoc --base-header-level=3 -V date:"" -V title:"" -f docbook foo.docbook -o foo.odt
With pandoc I have to nullify the date and title and set the header-level as desired for the section to be inserted as an extra complication.
I insert the resulting .odt into the main document using insert section inside open office.
Note that the main document is not a master document as I could not find a way of creating a master document without also automatically splitting the file on h1 boundaries.
I have two main problems to resolve with this set-up. I would like to add headings in the asciidoc document as cross references and also create entries for them in the alphabetical index (actually the first heading would be suffcient). Is there a way to do this?
Index markers in asciidoc do not result in entries in .odt file being created.
I am able to cross reference content in the inserted section using "insert reference/heading" and referencing the uniquely named header. However, whenever I use "update all" these cross references are invalidated. They are shown as "Error: Reference source not found".
[On a separate note I would also like a way to find broken cross references automatically]
I am currently using libreoffice - Version: 4.3.7.2
I am not adverse to switching version or flavours (i.e. apache) if one behaves better than the other.
I'm not sure if the answer is in the asciidoc or docbook parts of the chain. I would accept an answer which inserts a index entry at the start of the inserted section (top of the .adoc/docbook file) automatically.
I am also open to changing my toolchain to something that will work.
For example I tried the asciidoc-odt backend and fell foul of https://github.com/dagwieers/asciidoc-odf/issues/47 which does not inspire confidence.
Using asciidoc-odt I avoid the need to create an intermediate docbook file. However, I still can't get the anchor to appear.
I can get a macro to create an anchor but at present I haven't figured out how to run the macro from the command line.
To create an anchor in DocBook, make an inline anchor in the .adoc file. For example, giving this to asciidoctor:
[[X1]]Section1
---------------
produced this:
<title>
<anchor xml:id="X1" xreflabel="[X1]"/>
Section1
</title>
Conversely, putting this on separate lines did not create an anchor tag in my test:
[[X1]]
Section 1
Now for some bad news. From the Pandoc User's Guide:
Internal links are currently supported for HTML formats (including HTML slide shows and EPUB), LaTeX, and ConTeXt.
I interpret this to mean that currently, Pandoc does not create internal links in Writer. When I tried it, the link was ignored.
Note: It looks like I did not answer all of your questions. If you want to ask more about LibreOffice cross references and headings (the big bold paragraph towards the end of the question), maybe you could make a separate question just for that part.
Is it possible to generate an automatic Table of Contents using Github Flavoured Markdown?
I created two options to generate a toc for github-flavored-markdown:
DocToc Command Line Tool (source) requires node.js
Installation:
npm install -g doctoc
Usage:
doctoc . to add table of contents to all markdown files in the current and all sub directories.
DocToc WebApp
If you want to try it online first, go to the doctoc site,
paste the link of the markdown page and it will generate a table of
content that you can insert at the top of your markdown file.
Github Wikis and Anchors
As Matthew Flaschen pointed out in the comments below, for its wiki pages GitHub previously didn't generate the anchors that doctoc depends on.
UPDATE: However, they fixed this issue.
GitHub Pages (which is basically a wrapper for Jekyll) appears to use kramdown, which implements all of Maruku, and therefore has support for an automatically generated table of contents via atoc attribute:
* auto-gen TOC:
{:toc}
The first line just starts an unordered list and is actually thrown away.
This results in a nested set of unordered lists, using the headers in the document.
Note: this should work for GitHub Pages, not GitHub Flavored Markdown (GFM) as used in comments or wiki pages. AFAIK a solution doesn't exist for that.
If you edit Markdown files with Vim, you can try this plugin vim-markdown-toc.
The usage is simple, just move your cursor to the place you want to append Table of Contents and run :GenTocGFM, done!
Screenshots:
Features:
Generate toc for Markdown files. (Support GitHub Flavored Markdown and Redcarpet)
Update existing toc.
Auto update toc on save.
Update March 2021: GitHub added an official workaround
READMEs now show a ToC like this as you scroll down into them:
demo: https://github.com/cirosantilli/test-git-web-interface/tree/master/d
It does not render inside the document as I wanted for better Ctrl + F, but it is better than nothing.
Also also works for non-README as well now, e.g.: https://github.com/cirosantilli/test-git-web-interface/blob/master/md.md
They also added a repository setting to enable disable that. It's so weird, who would ever want to disable it? Under https://github.com/cirosantilli/test-git-web-interface/settings Features:
Table of contents
Autogenerate table of contents for Markdown files in this repository. The table of contents will be displayed near the top of the file.
Original answer
It's not possible, except for the workarounds proposed.
I proposed Kramdown TOC extension and other possibilities to support#github.com and Steven! Ragnarök replied with the usual:
Thanks for the suggestion and links. I'll add it to our internal feature request list for the team to see.
Let's upvote this question until it happens.
Another workaround is to use Asciidoc instead of Markdown, which does render TOCs. I've moved to this approach for my content nowadays.
It's not automatic, but it uses Notepad++ regular expressions:
Replace all first by the second (removes all lines not having headers)
^##(#?)(#?)(.*?)$(.|\r|\n)*?(?=^##|\z)
-\1\2 [\3](#\3)\n
Then (converts headers III to spaces)
-##
-
Then (converts headers II to spaces)
-#
-
Then (remove unused chars at the beginning and at the end of link title)
\[ *((?:(?![ .:#!\?;]*\])[^#])*)[ #:!\?;]*\]
[\1]
Then (convert last tokens lowercase and dash instead of spaces)
\]([^ \r\n]*) ([^\r\n ]*)
]\L\1-\2
Remove unused final pounds and initial dashes:
(?:()[-:;!\?#]+$|(\]#)-)
\1\2
Remove useless chars in links:
(\].*?)(?:\(|\))
\1
And finally add parenthesis around final links:
\](?!\()(.*?)$
\]\(\1\)
And voilà! You can even put this in a global macro if you repeat it enough time.
Github Flavored Markdown uses RedCarpet as their Markdown engine.
From the RedCarpet repo:
:with_toc_data - add HTML anchors to each header in the output HTML,
to allow linking to each section.
It seems in that you'd need to get at the renderer level to set this flag, which isn't possible on Github obviously. However, the latest update to Github Pages, it seems that automatic anchoring is turned on for headers, creating linkable headings. Not exactly what you want, but it might help you create a TOC for your doc a bit easier (albeit manually).
A very convenient way to achieve a table of contents for a mardown file when working with Visual Studio Code is the extension Markdown-TOC.
It can add a toc to existing markdown files and even keep the toc up-to-date on saving.
It is possible to generate a webpage automatically with http://documentup.com/ from the README.md file. It's not creating a TOC, but for many it might solve the reason for wanting to create a TOC.
Another alternative to Documentup is Flatdoc: http://ricostacruz.com/flatdoc/
Gitdown is a markdown preprocessor for Github.
Using Gitdown you can:
Generate Table of Contents
Find dead URLs and Fragment Identifiers
Include variables
Include files
Get file size
Generate Badges
Print Date
Print information about the repository itself
Gitdown streamlines common tasks associated with maintaining a documentation page for a GitHub repository.
Using it is straightforward:
var Gitdown = require('gitdown');
Gitdown
// Gitdown flavored markdown.
.read('.gitdown/README.md')
// GitHub compatible markdown.
.write('README.md');
You can either have it as a separate script or have it as part of the build script routine (such as Gulp).
Use coryfklein/doctoc, a fork of thlorenz/doctoc that does not add "generated with DocToc" to every table of contents.
npm install -g coryfklein/doctoc
Majority of other answers require to install some tool.
I found a quick and easy online solution https://imthenachoman.github.io/nGitHubTOC.
For any markdown input it generates table of content output.
You can specify minimum and maximum heading level.
The source code is located at https://github.com/imthenachoman/nGitHubTOC
My colleague #schmiedc and I have created a GreaseMonkey script that installs a new TOC button left of the h1 button which uses the excellent markdown-js library to add/refresh a table of contents.
The advantage over solutions like doctoc is that it integrates into GitHub's wiki editor and does not need users to work on their command-line (and require users to install tools like node.js). In Chrome, it works by drag 'n dropping into the Extensions page, in Firefox you will need to install the GreaseMonkey extension.
It will work with plain markdown (i.e. it does not handle code blocks correctly, as that is a GitHub extension to markdown). Contributions welcome.
This is a not a direct answer to this question as so many people have provided workarounds. I don't think generating a TOC has been officially supported by Github yet to-date. If you want GitHub to render a Table of Contents on their GFM preview pages automatically, please participate the discussion on the official feature request issue.
Shameless "borrow" of this SO answer.
You can do this with Pandoc.
pandoc -s --toc input.md -o input_toc.md
Note: the order of the input and output files is important here.
Currently it's not possible using markdown syntax (see the ongoing discussion at GitHub), however you can use some external tools such as:
Online Table Of Content Generator (raychenon/play-table-of-contents)
arthurhammer/github-toc - browser extension that adds a table of contents to GitHub repos
Alternatively use AsciiDoc instead (e.g. README.adoc), e.g.
:toc: macro
:toc-title:
:toclevels: 99
# Title
## A
### A2
## B
### B2
as suggested in this comment. Check the demo here.
For Github's Texteditor Atom check out this awesome plugin (or "package" in Atom-lingo), which generates "TOC (table of contents) of headlines from parsed markdown" files:
markdown-toc
Once installed as Atom-package you can use the shortcut ctrl-alt-c to insert a TOC based on your markdown-doc-structure at the current cursor position...
Screenshots:
Atom Keybindings
markdown-toc gives you the following default key-bindings to control the plugin in Atom:
ctrl-alt-c => create TOC at cursor position
ctrl-alt-u => update TOC
ctrl-alt-r => delete TOC
Plugin Features (from the project's README)
Auto linking via anchor tags, e.g. # A 1 → #a-1
Depth control [1-6] with depthFrom:1 and depthTo:6
Enable or disable links with withLinks:1
Refresh list on save with updateOnSave:1
Use ordered list (1. ..., 2. ...) with orderedList:0
Here's a shell script I threw together today for this. Might need to tweak it for your needs, but it should be a good starting point.
cat README.md \
| sed -e '/```/ r pf' -e '/```/,/```/d' \
| grep "^#" \
| tail -n +2 \
| tr -d '`' \
| sed 's/# \([a-zA-Z0-9`. -]\+\)/- [\1](#\L\1)/' \
| awk -F'(' '{for(i=2;i<=NF;i++)if(i==2)gsub(" ","-",$i);}1' OFS='(' \
| sed 's/^####/ /' \
| sed 's/^###/ /' \
| sed 's/^##/ /' \
| sed 's/^#//'
If anyone knows a better way to do those final # replacements, please add a comment. I tried various things and wasn't happy with any, so I just brute forced it.
There's now a GitHub Action accomplishing this:
https://github.com/marketplace/actions/toc-generator
Specify location of TOC (option)
e.g. README.md
<!-- START doctoc -->
<!-- END doctoc -->
Setup workflow
e.g. .github/workflows/toc.yml
on: push
name: TOC Generator
jobs:
generateTOC:
name: TOC Generator
runs-on: ubuntu-latest
steps:
- uses: technote-space/toc-generator#v2
Update 2022-02
In VSCode, check out extension "Markdown All in One". It will generate and update the TOC of markdown automatically.
Install Extension.
Place cursor at where you want to insert TOC.
Run command "Markdown All in One: Create Table of Contents"
Enjoy!
I need to refer to Doxygen documentation pages. The file names however are not stable as they change after every generation. My idea is to create a symlink to each HTML file created by Doxygen , having a stable and human friendly name. Have anyone tried this?
Actually, it might be very easy just to parse the annotated.html file Doxygen produces. Any documented class shows up there as a line like:
`<tr><td class="indexkey"><a class="el" href="dd/de6/a00548.html">
ImportantClass</a></td>`
The hard problem for me is that I would like to have my file names (i.e. the symlinks) be visible on my server like:
http://www.package.com/com.package.my.ImportantClass.html
[Yes, the code is in java]. So the question actually reads: "how to connect a HTML page by Doxygen with the right java class name and its package name.
You seem to have SHORT_NAMES enabled, which will indeed produce volatile names. When you set SHORT_NAMES to NO in the configuration file (the default), you will get longer names, but these are stable over multiple runs (i.e. they are based on the name, and for functions also on (a hash of) the parameters.