How to write a table of contents in a Readme.md?

[Guillaume]

Hi,

I'm trying to add a table of contents into a Readme.md for one of my repositories but I can't find a way to do it.

I tried to use the same syntax as GitHub, something similar to:

# Table of Contents

1. [My first title](#my-first-title)
2. [My second title](#my-second-title)
## My first title
Some text.
## My second title

But it doesn't work. Nothing happens when I click on the links generated into the ToC.

I'm running Bitbucket server 5.4. Is it possible to do such a thing please? I didn't find anything relevant into the Atlassian documentation.

Thanks for your help.

Guillaume.

[smolkin · Accepted solution]

For bitbucket server:

1. [ Description. ](#desc)
2. [ Usage tips. ](#usage)

<a name="desc"></a>
## 1. Description

sometext

<a name="usage"></a>
## 2. Usage tips

sometext

[Guillaume]

It works! Thank you very much!

[hh-lohmann]

Obviously works because, as you said, you are hosting your own bitbucket server.

Others, reading this post and using bitbucket.org: Markdown on bitbucket.org does not allow HTML tags (for security reasons). github.com and other Markdown environments do, so in a common Markdown editor on your PC it should work, but you cannot publish that on bitbucket.org.

[hh-lohmann]

On bitbucket.org, just write "[TOC]", see https://confluence.atlassian.com/bitbucket/add-a-table-of-contents-to-a-wiki-221451163.html

For other editors see their references. Retext, e.g., and maybe any Python based Markdown editor, allow to define "extensions", one of which is "markdown.extensions.toc" which provides the "[TOC]" functionality.

[limanzhang]

It works! Thank you so much!

[Tim Black]

This is a Bitbucket server question, and [TOC] does not work on Bitbucket server.

The accepted answer basically just shows how to do this with manually-written html anchors and references/links. I'm looking for a way to have this TOC generated from existing headers.

A search for "table of contents" for Bitbucket Server produces zero hits:

https://confluence.atlassian.com/search/?productName=Bitbucket&productVersion=6.2&queryString=%22table%20of%20contents%22

Anyone know how to autogenerate TOC in Bitbucket Server? We're on 6.2.

Looks like it can be done with external software, like this, or this. But I would really like for this to be done in Bitbucket without having to add any of my own "glue"..

[Graham Hannington]

Atlassian,

Please add [TOC] (and other extensions?) to Bitbucket Server.

[Levi Moore]

You need to add "markdown-header-" to your link parentheses.

1. [My First Title](#markdown-header-my-first-title)

2. [My Second Title](#markdown-header-my-second-title)

This worked for me.

[D K]

This didn't work for me I tried with and without `markdown-header-`

[Chris Black]

Same for me... does not work...

[Saad Benbouzid]

same here, doesn't work...

[hh-lohmann]

Unfortunately you depend on the editor you are using. The built-in one on bitbucket.org creates for a "##My First Title" headline an anchor "markdown-header-my-first-title", other editors may create an anchor "my_first_title", "My_First_Title_0", etc. - and some might produce no anchor at all. The reason is that this is no part of Markdown, but just a "service" from some editors.

[John Lawlor]

This seems to be related to the quite old version of CommonMark (which Bitbucket README markdown is based on) bundled into Bitbucket server.

[user@server app]$ find . -name "*.jar" | grep common 
./WEB-INF/atlassian-bundled-plugins/atlassian-remote-event-common-plugin-6.2.2.jar 
./WEB-INF/atlassian-bundled-plugins/bitbucket-ao-common-7.9.0.jar 
./WEB-INF/lib/atlassian-cache-common-impl-5.3.3.jar 
./WEB-INF/lib/commonmark-0.15.2.jar 
./WEB-INF/lib/commons-beanutils-1.9.4.jar 
./WEB-INF/lib/commons-codec-1.14.jar 
./WEB-INF/lib/commons-compiler-2.7.8.jar 
./WEB-INF/lib/commons-compress-1.19.jar 
./WEB-INF/lib/atlassian-extras-common-3.4.1.jar 
./WEB-INF/lib/commons-digester-1.8.1.jar 
./WEB-INF/lib/commons-fileupload-1.3.3.jar 
./WEB-INF/lib/commons-io-2.6.jar 
./WEB-INF/lib/commons-lang-2.6.jar 
./WEB-INF/lib/commons-lang3-3.8.1.jar 
./WEB-INF/lib/commons-pool-1.6.jar 
./WEB-INF/lib/commons-validator-1.4.1.jar 
./WEB-INF/lib/atlassian-plugins-webresource-common-5.4.0-01c481fbd.jar 
./WEB-INF/lib/bitbucket-git-common-7.9.0.jar 
./WEB-INF/lib/bitbucket-scm-common-7.9.0.jar 
./WEB-INF/lib/bitbucket-web-common-7.9.0.jar 
./WEB-INF/lib/commonmark-ext-autolink-0.15.2.jar 
./WEB-INF/lib/commonmark-ext-gfm-strikethrough-0.15.2.jar 
./WEB-INF/lib/commonmark-ext-gfm-tables-0.15.2.jar 
./WEB-INF/lib/commonmark-ext-heading-anchor-0.15.2.jar 
./WEB-INF/lib/commonmark-ext-image-attributes-0.15.2.jar 
./WEB-INF/lib/commons-collections-3.2.2.jar 
./WEB-INF/lib/crowd-common-4.1.6.jar 
./WEB-INF/lib/crowd-integration-client-common-4.1.6.jar 
./WEB-INF/lib/crowd-rest-common-4.1.6.jar 
./WEB-INF/lib/crowd-server-common-4.1.6.jar 
./WEB-INF/lib/hibernate-commons-annotations-5.1.2.Final.jar 
./WEB-INF/lib/istack-commons-runtime-3.0.7.jar 
./WEB-INF/lib/netty-common-4.1.53.Final.jar 
./WEB-INF/lib/netty-transport-native-unix-common-4.1.53.Final.jar 
./WEB-INF/lib/proto-google-common-protos-1.17.0.jar 
./WEB-INF/osgi-framework-bundles/commons-lang-2.6.jar 
./WEB-INF/osgi-framework-bundles/commons-pool-1.6.jar 
./WEB-INF/savant/commons-text-1.8.jar 

The bundled version (0.15.2) is from 2014, it could do with an update.
See also: https://jira.atlassian.com/browse/BSERV-11795
  

[Tim Black]

It's not possible with BB Server out of the box. Please vote for one or bothfboth othe related feature requests:

https://jira.atlassian.com/browse/BSERV-12289

https://jira.atlassian.com/browse/BSERV-10895

[aapetroaei]

Try to use it like this:
1. [Description.](#markdown-header-desc)

[Gonchik Tsymzhitov]

Hi Guillaume, 

Have you tried this tutorial for README.md? 

https://bitbucket.org/tutorials/markdowndemo/overview#markdown-header-tables

Hope it helps.

Cheers,

Gonchik Tsymzhitov

[Guillaume]

Hi Gonchik,

Thank you for your help, but it doesn't answered my question. I'm not trying to create a table (I have no problems for this), but a table of contents.

Like:

In other words: a list of links to the titles inside the README.

Guillaume.

[Nuriddin]

### Pythonda vektorlar haqida tushuncha va ularning taqqoslanishi.


#### Vektor nima?

Oddiy so'z bilan aytganda vektorni bir o'lchovli massiv deb hisoblash mumkin. Python tiliga kelsak, vektor ro'yxatlarning bir o'lchovli massividir. U elementlarni Python ro'yxatiga o'xshash tarzda egallaydi.

* Massiv: <br>

Dasturlash tillarida ro’yxat yoki jadval ko’rinishidagi ma’lumotlarni massiv deb atashadi. Massiv so’zining ma’nosi o’lcham, o’lchov demakdir. Massivning barcha elementlari bitta turga mansub bo’lib, ular bitta nom bilan nomlanadi va bir-birlaridan nomerlari (indekslari) bilan farq qiladi.

#### Vektor yaratish

Python NumPy moduli vektor yaratish uchun ishlatiladi. Bir o'lchovli massiv, ya'ni vektor yaratish uchun numpy.array() metodidan foydalanamiz.

Syntax:

```python
numpy.array(list)
```

Example 1: Gorizontal vektor

```python
import numpy as np 

lst = [10, 20, 30, 40, 50] 

vctr = np.array(lst) 

print("List buyicha yaratilgan vektor:") 
print(vctr)
```
Output:
```terminal
List buyicha yaratilgan vektor:
[10 20 30 40 50]
```

Example 2: Vertikal Vector

```python
import numpy as np 

lst = [[2], 
        [4], 
        [6],
          [10]]  

vctr = np.array(lst) 

print("List buyicha yaratilgan vektor:") 
print(vctr)
```

Output:
```python
List buyicha yaratilgan vektor:
[[ 2]
 [ 4]
 [ 6]
 [10]]
```

#### Python vektorida asosiy operatsiyalar

Vektorni yaratgandan so'ng, keling, endi ushbu Vektorlar ustida bir nechta asosiy operatsiyalarni bajaramiz! <br>
Quyidagilar vektorda bajarilishi mumkin bo'lgan asosiy operatsiyalar ro'yxati - 

* Addition (qo'shish)
* Subtraction (ayirish)
* Multiplication (ko'paytirish)
* Division (bo'lish)
* Dot Product (nuqta amali) va boshqalar

#### 1. Python vektorida qo'shish operatsiyasini bajarish

Bunda ikki vektorning elementlari bo'yicha amal bajariladi va ikkala vektorning ham uzunligi bir xil bo'ladi.

Example:

```python
import numpy as np 

lst1 = [10, 20, 30, 40, 50] 
lst2 = [1, 2, 3, 4, 5]


vctr1 = np.array(lst1) 

vctr2= np.array(lst2) 


print("list 1 dan vektor yaratildi:") 
print(vctr1) 
print("list 2 dan vektor yaratildi:") 
print(vctr2) 

vctr_add = vctr1 + vctr2
print("Vektorlarning yig'indisi: ",vctr_add)
```

Output:
```console
list 1 dan vektor yaratildi:
[10 20 30 40 50]
list 2 dan vektor yaratildi:
[1 2 3 4 5]
Vektorlarning yig'indisi:  [11 22 33 44 55]
```

#### 2. Python vektorida ayirish operatsiyasini bajarish

Example:

```python
import numpy as np 

lst1 = [10, 20, 30, 40, 50] 
lst2 = [1, 2, 3, 4, 5]


vctr1 = np.array(lst1) 

vctr2= np.array(lst2) 


print("list 1 dan vektor yaratildi:") 
print(vctr1) 
print("list 2 dan vektor yaratildi:") 
print(vctr2) 

vctr_sub = vctr1-vctr2
print("Vektorlarning ayirmasi: ",vctr_sub)
```

Output:
```console
list 1 dan vektor yaratildi:
[10 20 30 40 50]
list 2 dan vektor yaratildi:
[1 2 3 4 5]
Vektorlarning ayirmasi:  [ 9 18 27 36 45]
```

#### 3. Python vektorida ko'paytirish operatsiyasini bajarish

Bunda ikki vektor elementlari ko'paytiriladi va ikkila vektor uzunligi teng bo'ladi.

Keling, ko'paytirish amalini tasavvur qilishga harakat qilaylik:  <br>
x = [10, 20] va y = [1, 2] ikkita vektor mavjud. Shunday qilib, mahsulot vektori v[ ] bo'ladi, <br>

v[0] = x[0] * y[0] <br>
v[1] = x[1] * y[1]

Quyidagi kodni ko'rib chiqing!

```python
import numpy as np 

lst1 = [10, 20, 30, 40, 50] 
lst2 = [1, 2, 3, 4, 5]

vctr1 = np.array(lst1) 

vctr2= np.array(lst2) 

print("list 1 dan vektor yaratildi:") 
print(vctr1) 
print("list 2 dan vektor yaratildi:") 
print(vctr2) 

vctr_mul = vctr1*vctr2
print("Vektorlaring ko'paytmasi: ",vctr_mul)
```

Output:
```console
list 1 dan vektor yaratildi:
[10 20 30 40 50]
list 2 dan vektor yaratildi:
[1 2 3 4 5]
Vektorlaring ko'paytmasi:  [ 10  40  90 160 250]
```

#### 4. Python vektorida bo'lish operatsiyasini bajarish

Yaxshiroq tushunish uchun quyidagi misolni ko'rib chiqing.

x = [10, 20] va y = [1, 2] ikkita vektor mavjud. Shunday qilib, mahsulot vektori v[ ] bo'ladi, <br>

v[0] = x[0] / y[0] <br>
v[1] = x[1] / y[1]

Example:
```python
import numpy as np 
 
lst1 = [10, 20, 30, 40, 50] 
lst2 = [10, 20, 30, 40, 50]
 
vctr1 = np.array(lst1) 
 
vctr2= np.array(lst2) 
 
print("list 1 dan vektor yaratildi:") 
print(vctr1) 
print("list 2 dan vektor yaratildi:") 
print(vctr2) 
 
vctr_div = vctr1/vctr2
print("Vektorlar bo'linmasi: ",vctr_div)
```

Output:
```console
list 1 dan vektor yaratildi:
[10 20 30 40 50]
list 2 dan vektor yaratildi:
[10 20 30 40 50]
Vektorlar bo'linmasi:  [ 1 1 1 1 1 ]
```

#### Vektor Dot 

Bu amalda biz ikki vektorning elementlari buyicha bajaramiz.
<br>
`Vektor Dot` amalini tushunib olish uchun quyidagi misolga e'tibor bering: <br>
`vector c = x . y = (x1 * y1 + x2 * y2)`

Example:
```python
import numpy as np 

lst1 = [10, 20, 30, 40, 50] 
lst2 = [1, 1, 1, 1, 1]


vctr1 = np.array(lst1) 

vctr2= np.array(lst2) 


print("list 1 dan vektor yaratildi:") 
print(vctr1) 
print("list 2 dan vektor yaratildi:") 
print(vctr2) 

vctr_dot = vctr1.dot(vctr2)
print("Vektor Dot amalinining natijasi: ",vctr_dot)
```

Output:
```console
list 1 dan vektor yaratildi:
[10 20 30 40 50]
list 2 dan vektor yaratildi:
[1 1 1 1 1]
Vektor Dot amalinining natijasi: 150
```

* Vektorlar haqida tushuncha hosil qilib oldik, endi vektorlarning qanday taqqoslanishini ko'rib chiqamiz.

#### Vektorlarni taqqoslash

Vektorlarni taqqoslanishini bir nechta usullari mavjud.
Masalan: 
Euclidean, Cosine, Hamming, Manhattan va boshqalar.

<p align="center">
    <img src="./image/vektor_taqqoslash_usullari.jpg">
</p>


Biz `cosine similarity` formulasi orqali vektorlarni taqqoslashni ko'rib o'tamiz.

<p align="center">
    <img src="./image/cosine_formulasi.png">
</p>

* Formuladagi amallarni pythonda tartib buyicha bajarib ko'ramiz.
<br>
* Vektorlarni hosil qilib olamiz.
```python
v1 = [1, 2, 3, 4, 5]
v2 = [1, 2, 3, 4, 5]
v3 = [1, 2, 3, 4, 6]
v4 = [100, 2, 3, 4, 5]
```
* Keling birinchi kasrning surat qismini bajarib olamiz. Bunda biz A va B vektorlarning elementlarini ko'paytirib qushib borishimiz kerak. Bu jarayonni `while` yordamida bajarib o'tamiz. Tushunarli bo'lishi uchun har bir jarayonni funksiya orqali bajarib o'tamiz.

```python
def surat(a,b):
    i = 0
    kasr_surati = 0
    while i < len(a):
        kasr_surati += (a[i] * b[i])
        i += 1
    return kasr_surati
```

* E'tibor bersangiz formulamizning maxraj qismida ildiz amali mavjud. Bu amalni bajarish uchun `ildiz` nomli funksiya yaratib o'tamiz va kerakli joyda funksiyani chaqirib ishlatamiz.

```python
def ildiz(x):
    return math.sqrt(x)
```

* Kasrning maxraj qismida bizdan vektorlarimizning xar bir elementini olib, va uni kvadratga oshirib, qushib borishimizni talab qilmoqda. Hosil bo'lgan yig'indilarni ildizlarining ko'paytmasini bajarib o'tishimiz lozim.
<br>
Maxraj qismining ishlanishi:

```python
def maxraj(a,b):
    # modul
    i = 0
    modul_a = 0
    modul_b = 0
    while i < len(a):
        modul_a += (a[i] * a[i])
        modul_b += (b[i] * b[i])
        i += 1

    modul_a = ildiz(modul_a)
    modul_b = ildiz(modul_b)
    kasr_maxraji = modul_a * modul_b
    return kasr_maxraji
```

* Endi biz `vector_taq` nomli yangi funksiya hosil qilib olamiz. Kasrning surat qismini maxraj qismiga bo'lsak yetarli.

```python
def vector_taq(a, b):
    # kosinus o'xshashlik https://en.wikipedia.org/wiki/Cosine_similarity
    # 1*1 + 2*2 + 2*2 + 1*2 + 1*1 + 1*1
    if len(a) == len(b):
        yaqinlik = surat(a,b) / maxraj(a,b)
        return yaqinlik
    else:
        print("Elementlar soni teng bo'lish kerak!")
```
* Yuqorida vektorlarning uzunliklari teng bulishligi lozim deb shart berib otdik. 

* Bajargan jarayonlarimizning umumiy ko'rinishi.

```python
import math

def surat(a,b):
    i = 0
    kasr_surati = 0
    while i < len(a):
        kasr_surati += (a[i] * b[i])
        i += 1
    return kasr_surati

def ildiz(x):
    return math.sqrt(x)

def maxraj(a,b):
    # modul
    i = 0
    modul_a = 0
    modul_b = 0
    while i < len(a):
        modul_a += (a[i] * a[i])
        modul_b += (b[i] * b[i])
        i += 1

    modul_a = ildiz(modul_a)
    modul_b = ildiz(modul_b)
    kasr_maxraji = modul_a * modul_b
    return kasr_maxraji

def vector_taq(a, b):
    # kosinus o'xshashlik https://en.wikipedia.org/wiki/Cosine_similarity
    # 1*1 + 2*2 + 2*2 + 1*2 + 1*1 + 1*1
    if len(a) == len(b):
        yaqinlik = surat(a,b) / maxraj(a,b)
        return yaqinlik
    else:
        print("Elementlar soni teng bo'lish kerak!")


v1 = [1, 2, 3, 4, 5]
v2 = [1, 2, 3, 4, 5]
v3 = [1, 2, 3, 4, 6]
v4 = [100, 2, 3, 4, 5]


natija1 = vector_taq(v1, v2)
natija2 = vector_taq(v1, v3)
natija3 = vector_taq(v1, v4)

print(natija1)
print(natija2)
print(natija3)
```

* Bajarib o'tkan dasturimizni ishlatib o'tsak quyidagi natijani olamiz.

```console
1.0
0.9958591954639383
0.20709515355464156
```

#### Vektorlarni taqqoslash uchun tayyor kutibxonadan foydalanish

* Vektorlarni taqqoslashda biz tayyor kutibxonadan foydalanishni ko'ramiz. Buning uchun biz `cosine_similarity` va `numpy` kutubxonalarini `import` qilib olishimiz lozim.

```python
from sklearn.metrics.pairwise import cosine_similarity
import numpy as np

v1 = [1, 2, 3, 4, 5]
v2 = [1, 2, 3, 4, 5]
v3 = [1, 2, 3, 4, 6]
v4 = [100, 2, 3, 4, 5]

natija1 = cosine_similarity(np.array(v1).reshape(1, -1), np.array(v2).reshape(1, -1))[0][0]
natija2 = cosine_similarity(np.array(v1).reshape(1, -1), np.array(v3).reshape(1, -1))[0][0]
natija3 = cosine_similarity(np.array(v1).reshape(1, -1), np.array(v4).reshape(1, -1))[0][0]

print(natija1)
print(natija2)
print(natija3)
```
* Yuqorida bajarib o'tkanimizdek bunda ham bir xil natijani olamiz.

```console
1.0
0.9958591954639383
0.2070951535546416
```